Skip to content

Commit 37d3f67

Browse files
posvaposva
committed
refactor: rename unbind() to stop()
BREAKING CHANGE: Composables like `useDocument()` no longer return an `unbind()` method. The method is now named `stop()` to better reflect that they also stop the Vue watcher on top of stopping the Firebase data subscription.
1 parent 3c08b19 commit 37d3f67

15 files changed

+91
-82
lines changed

‎src/database/index.ts

+12-14
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ import { databaseUnbinds } from './optionsApi'
2626
import {
2727
bindAsArray,
2828
bindAsObject,
29-
rtdbOptions,
29+
databaseOptionsDefaults,
3030
_DatabaseRefOptions,
3131
} from './subscribe'
3232
import {
@@ -54,8 +54,8 @@ export function _useDatabaseRef(
5454
reference: _MaybeRef<_Nullable<DatabaseReference | Query>>,
5555
localOptions: UseDatabaseRefOptions = {}
5656
) {
57-
let _unbind!: UnbindWithReset
58-
const options = Object.assign({}, rtdbOptions, localOptions)
57+
let unbind!: UnbindWithReset
58+
const options = Object.assign({}, databaseOptionsDefaults, localOptions)
5959
const initialSourceValue = unref(reference)
6060

6161
const data = options.target || ref<unknown | null>()
@@ -74,13 +74,13 @@ export function _useDatabaseRef(
7474

7575
const p = new Promise<unknown | null>((resolve, reject) => {
7676
if (!referenceValue) {
77-
_unbind = noop
77+
unbind = noop
7878
// resolve to avoid an ever pending promise
7979
return resolve(null)
8080
}
8181

8282
if (Array.isArray(data.value)) {
83-
_unbind = bindAsArray(
83+
unbind = bindAsArray(
8484
{
8585
target: data,
8686
collection: referenceValue,
@@ -91,7 +91,7 @@ export function _useDatabaseRef(
9191
options
9292
)
9393
} else {
94-
_unbind = bindAsObject(
94+
unbind = bindAsObject(
9595
{
9696
target: data,
9797
document: referenceValue,
@@ -132,30 +132,28 @@ export function _useDatabaseRef(
132132
}
133133

134134
if (hasCurrentScope) {
135-
onScopeDispose(unbind)
135+
onScopeDispose(stop)
136136

137137
// wait for the promise on SSR
138138
if (getCurrentInstance()) {
139139
onServerPrefetch(() => promise.value)
140140
}
141141
}
142142

143-
// TODO: rename to stop
144-
function unbind(reset: ResetOption = options.reset) {
143+
function stop(reset: ResetOption = options.reset) {
145144
stopWatcher()
146145
removePendingPromise()
147-
_unbind(reset)
146+
unbind(reset)
148147
}
149148

150149
return Object.defineProperties(data as _RefDatabase<unknown>, {
151150
// allow destructuring without interfering with the ref itself
152151
data: { get: () => data },
153152
error: { get: () => error },
154-
pending: { get: () => error },
155-
153+
pending: { get: () => pending },
156154
promise: { get: () => promise },
157-
unbind: { get: () => unbind },
158-
}) as _RefDatabase<unknown | null>
155+
stop: { get: () => stop },
156+
})
159157
}
160158

161159
export function internalUnbind(

‎src/database/optionsApi.ts

+5-6
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,12 @@ import { useFirebaseApp } from '../app'
66
import { getGlobalScope } from '../globals'
77
import { ResetOption, UnbindWithReset } from '../shared'
88
import { internalUnbind, _useDatabaseRef } from './index'
9-
import { _DatabaseRefOptions, _GlobalDatabaseRefOptions } from './subscribe'
9+
import { _DatabaseRefOptions } from './subscribe'
1010

1111
/**
12-
* Options for the Firebase Database Plugin that enables the Options API such as `$rtdbBind` and `$rtdbUnbind`.
12+
* Options for the Firebase Database Plugin that enables the Options API such as `$databaseBind` and `$databaseUnbind`.
1313
*/
14-
export interface DatabasePluginOptions
15-
extends Partial<_GlobalDatabaseRefOptions> {
14+
export interface DatabasePluginOptions extends _DatabaseRefOptions {
1615
/**
1716
* @deprecated: was largely unused and not very useful. Please open an issue with use cases if you need this.
1817
*/
@@ -25,7 +24,7 @@ export interface DatabasePluginOptions
2524
}
2625

2726
const databasePluginDefaults: Readonly<
28-
Required<Omit<DatabasePluginOptions, keyof _GlobalDatabaseRefOptions>>
27+
Required<Omit<DatabasePluginOptions, keyof _DatabaseRefOptions>>
2928
> = {
3029
bindName: '$databaseBind',
3130
unbindName: '$databaseUnbind',
@@ -109,7 +108,7 @@ export function databasePlugin(
109108
effectScope()
110109
)!
111110

112-
const { promise, unbind: _unbind } = scope.run(() =>
111+
const { promise, stop: _unbind } = scope.run(() =>
113112
_useDatabaseRef(source, { target, ...options })
114113
)!
115114

‎src/database/subscribe.ts

+15-6
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,12 @@ import {
33
indexForKey,
44
DatabaseSnapshotSerializer,
55
} from './utils'
6-
import { OperationsType, ResetOption, _DataSourceOptions } from '../shared'
6+
import {
7+
noop,
8+
OperationsType,
9+
ResetOption,
10+
_DataSourceOptions,
11+
} from '../shared'
712
import { ref, Ref, unref } from 'vue-demi'
813
import type { Query, DatabaseReference } from 'firebase/database'
914
import {
@@ -14,12 +19,17 @@ import {
1419
onChildRemoved,
1520
} from 'firebase/database'
1621

17-
// TODO: rename to match where it's used
22+
/**
23+
* Global option type when binding one database reference
24+
*/
1825
export interface _DatabaseRefOptions extends _DataSourceOptions {
1926
serialize?: DatabaseSnapshotSerializer
2027
}
2128

22-
export interface _GlobalDatabaseRefOptions extends _DatabaseRefOptions {
29+
/**
30+
* Global defaults type override options for all database bindings.
31+
*/
32+
interface _DefaultsDatabaseRefOptions extends _DatabaseRefOptions {
2333
/**
2434
* @defaultValue `false`
2535
*/
@@ -32,14 +42,13 @@ export interface _GlobalDatabaseRefOptions extends _DatabaseRefOptions {
3242
serialize: DatabaseSnapshotSerializer
3343
}
3444

35-
const DEFAULT_OPTIONS: _GlobalDatabaseRefOptions = {
45+
const DEFAULT_OPTIONS: _DefaultsDatabaseRefOptions = {
3646
reset: false,
3747
serialize: createRecordFromDatabaseSnapshot,
3848
wait: true,
3949
}
4050

41-
// TODO: rename rtdbDefaults databaseDefaults
42-
export { DEFAULT_OPTIONS as rtdbOptions }
51+
export { DEFAULT_OPTIONS as databaseOptionsDefaults }
4352

4453
interface CommonBindOptionsParameter {
4554
target: Ref<any>

‎src/firestore/index.ts

+10-11
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ import { firestoreUnbinds } from './optionsApi'
3838
import {
3939
bindCollection,
4040
bindDocument,
41-
firestoreOptions,
41+
firestoreOptionsDefaults,
4242
FirestoreRefOptions,
4343
} from './subscribe'
4444

@@ -63,8 +63,8 @@ export function _useFirestoreRef(
6363
>,
6464
localOptions?: _UseFirestoreRefOptions
6565
) {
66-
let _unbind: UnbindWithReset = noop
67-
const options = Object.assign({}, firestoreOptions, localOptions)
66+
let unbind: UnbindWithReset = noop
67+
const options = Object.assign({}, firestoreOptionsDefaults, localOptions)
6868
const initialSourceValue = unref(docOrCollectionRef)
6969

7070
const data = options.target || ref<unknown | null>()
@@ -83,12 +83,12 @@ export function _useFirestoreRef(
8383

8484
const p = new Promise<unknown | null>((resolve, reject) => {
8585
// stop the previous subscription
86-
_unbind(options.reset)
86+
unbind(options.reset)
8787
// skip if the ref is null or undefined
8888
// we still want to create the new promise
8989
if (!docRefValue) {
90-
_unbind = noop
91-
// TODO: maybe we shouldn't resolve this at all?
90+
unbind = noop
91+
// resolve to avoid an ever pending promise
9292
return resolve(null)
9393
}
9494

@@ -100,7 +100,7 @@ export function _useFirestoreRef(
100100
}
101101

102102
// FIXME: force once on server
103-
_unbind = (isDocumentRef(docRefValue) ? bindDocument : bindCollection)(
103+
unbind = (isDocumentRef(docRefValue) ? bindDocument : bindCollection)(
104104
// @ts-expect-error: cannot type with the ternary
105105
data,
106106
docRefValue,
@@ -142,19 +142,18 @@ export function _useFirestoreRef(
142142
// should take an option like once: true to not setting up any listener
143143

144144
if (hasCurrentScope) {
145-
onScopeDispose(unbind)
145+
onScopeDispose(stop)
146146
if (getCurrentInstance()) {
147147
// wait for the promise during SSR
148148
// TODO: configurable ssrKey: false to disable this
149149
onServerPrefetch(() => promise.value)
150150
}
151151
}
152152

153-
// TODO: rename to stop
154-
function unbind(reset: ResetOption = options.reset) {
153+
function stop(reset: ResetOption = options.reset) {
155154
stopWatcher()
156155
removePendingPromise()
157-
_unbind(reset)
156+
unbind(reset)
158157
}
159158

160159
// allow to destructure the returned value

‎src/firestore/optionsApi.ts

+4-5
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ import type {
66
} from 'firebase/firestore'
77
import { App, ComponentPublicInstance, effectScope, toRef } from 'vue'
88
import { isVue3 } from 'vue-demi'
9-
import { FirestoreRefOptions, _GlobalFirestoreRefOptions } from './subscribe'
9+
import { FirestoreRefOptions } from './subscribe'
1010
import { internalUnbind, _useFirestoreRef } from '.'
1111
import { ResetOption, UnbindWithReset, _FirestoreDataSource } from '../shared'
1212
import { FirebaseApp } from 'firebase/app'
@@ -27,8 +27,7 @@ export const firestoreUnbinds = new WeakMap<
2727
* Options for the Firebase Database Plugin that enables the Options API such as `$firestoreBind` and
2828
* `$firestoreUnbind`.
2929
*/
30-
export interface FirestorePluginOptions
31-
extends Partial<_GlobalFirestoreRefOptions> {
30+
export interface FirestorePluginOptions extends FirestoreRefOptions {
3231
/**
3332
* @deprecated: was largely unused and not very useful. Please open an issue with use cases if you need this.
3433
*/
@@ -41,7 +40,7 @@ export interface FirestorePluginOptions
4140
}
4241

4342
const firestorePluginDefaults: Readonly<
44-
Required<Omit<FirestorePluginOptions, keyof _GlobalFirestoreRefOptions>>
43+
Required<Omit<FirestorePluginOptions, keyof FirestoreRefOptions>>
4544
> = {
4645
bindName: '$firestoreBind',
4746
unbindName: '$firestoreUnbind',
@@ -104,7 +103,7 @@ export const firestorePlugin = function firestorePlugin(
104103
effectScope()
105104
)!
106105

107-
const { promise, unbind: _unbind } = scope.run(() =>
106+
const { promise, stop: _unbind } = scope.run(() =>
108107
_useFirestoreRef(docOrCollectionRef, {
109108
target,
110109
...options,

‎src/firestore/subscribe.ts

+11-6
Original file line numberDiff line numberDiff line change
@@ -38,13 +38,18 @@ export interface FirestoreRefOptions extends _DataSourceOptions {
3838
* @inheritDoc {SnapshotListenOptions}
3939
*/
4040
snapshotListenOptions?: SnapshotListenOptions
41+
42+
/**
43+
* Default Firestore converter to use with snapshots.
44+
*/
45+
converter?: FirestoreDataConverter<unknown>
4146
}
4247

4348
/**
4449
* Type of the global options for firestore refs. Some values cannot be `undefined`.
4550
* @internal
4651
*/
47-
export interface _GlobalFirestoreRefOptions extends FirestoreRefOptions {
52+
interface _DefaultsFirestoreRefOptions extends FirestoreRefOptions {
4853
/**
4954
* @defaultValue `false`
5055
*/
@@ -65,13 +70,13 @@ export interface _GlobalFirestoreRefOptions extends FirestoreRefOptions {
6570
converter: FirestoreDataConverter<unknown>
6671
}
6772

68-
const DEFAULT_OPTIONS: _GlobalFirestoreRefOptions = {
73+
const DEFAULT_OPTIONS: _DefaultsFirestoreRefOptions = {
6974
reset: false,
7075
wait: true,
7176
maxRefDepth: 2,
7277
converter: firestoreDefaultConverter,
7378
}
74-
export { DEFAULT_OPTIONS as firestoreOptions }
79+
export { DEFAULT_OPTIONS as firestoreOptionsDefaults }
7580

7681
interface FirestoreSubscription {
7782
unsub: () => void
@@ -89,7 +94,7 @@ function unsubscribeAll(subs: Record<string, FirestoreSubscription>) {
8994
}
9095

9196
function updateDataFromDocumentSnapshot<T>(
92-
options: _GlobalFirestoreRefOptions,
97+
options: _DefaultsFirestoreRefOptions,
9398
target: Ref<T>,
9499
path: string,
95100
snapshot: DocumentSnapshot<T>,
@@ -120,7 +125,7 @@ interface SubscribeToDocumentParameter {
120125

121126
function subscribeToDocument(
122127
{ ref, target, path, depth, resolve, ops }: SubscribeToDocumentParameter,
123-
options: _GlobalFirestoreRefOptions
128+
options: _DefaultsFirestoreRefOptions
124129
) {
125130
const subs = Object.create(null)
126131
const unbind = onSnapshot(ref, (snapshot) => {
@@ -151,7 +156,7 @@ function subscribeToDocument(
151156
// first one is calling the other on every ref and subscribeToDocument may call
152157
// updateDataFromDocumentSnapshot which may call subscribeToRefs as well
153158
function subscribeToRefs(
154-
options: _GlobalFirestoreRefOptions,
159+
options: _DefaultsFirestoreRefOptions,
155160
target: Ref<unknown>,
156161
path: string | number,
157162
subs: Record<string, FirestoreSubscription>,

‎src/shared.ts

+5-4
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
import { DatabaseReference, Query as DatabaseQuery } from 'firebase/database'
2-
import type {
2+
import {
33
CollectionReference,
44
DocumentData,
55
DocumentReference,
66
DocumentSnapshot,
77
Query as FirestoreQuery,
88
QuerySnapshot,
9+
Timestamp,
910
} from 'firebase/firestore'
1011
import type { Ref, ShallowRef } from 'vue-demi'
1112

@@ -33,7 +34,7 @@ export interface OperationsType {
3334
export type ResetOption = boolean | (() => unknown)
3435

3536
/**
36-
* Return type of `$rtdbBind()` and `$firestoreBind()`
37+
* Return type of `$databaseBind()` and `$firestoreBind()`
3738
*/
3839
export type UnbindWithReset = (reset?: ResetOption) => void
3940

@@ -94,7 +95,7 @@ export function isObject(o: any): o is Record<any, unknown> {
9495
* Checks if a variable is a Date
9596
* @param o
9697
*/
97-
export function isTimestamp(o: any): o is Date {
98+
export function isTimestamp(o: any): o is Timestamp {
9899
return o.toDate
99100
}
100101

@@ -206,7 +207,7 @@ export interface _RefWithState<T, E = Error> extends Ref<T> {
206207
/**
207208
* Stops listening to the data changes and stops the Vue watcher.
208209
*/
209-
unbind: (reset?: ResetOption) => void
210+
stop: (reset?: ResetOption) => void
210211
}
211212

212213
/**

0 commit comments

Comments
 (0)