teamplay 0.5.0-alpha.24 → 0.5.0-alpha.26

package/dist/index.d.ts

@@ -53,7 +53,8 @@ export { default as signal } from './orm/getSignal.js';
 export { GLOBAL_ROOT_ID } from './orm/Root.js';
 export declare const $: RootSignal;
 export default $;
-export { default as sub } from './orm/sub.js';
+export { default as sub, unsub } from './orm/sub.js';
+export type { SubMode, SubOptions } from './orm/sub.js';
 export { default as useSub, useAsyncSub, useBatchSub, setUseDeferredValue as __setUseDeferredValue, setDefaultDefer as __setDefaultDefer } from './react/useSub.js';
 export { default as useSuspendMemo, useSuspendMemoByKey } from './react/useSuspendMemo.js';
 export declare const observer: ObserverFunction;

package/dist/index.js

@@ -14,7 +14,7 @@ export { GLOBAL_ROOT_ID } from "./orm/Root.js";
 const getRuntimeRootSignal = _getRootSignal;
 export const $ = getRuntimeRootSignal({ rootId: GLOBAL_ROOT_ID, rootFunction: universal$ });
 export default $;
-export { default as sub } from "./orm/sub.js";
+export { default as sub, unsub } from "./orm/sub.js";
 export { default as useSub, useAsyncSub, useBatchSub, setUseDeferredValue as __setUseDeferredValue, setDefaultDefer as __setDefaultDefer } from "./react/useSub.js";
 export { default as useSuspendMemo, useSuspendMemoByKey } from "./react/useSuspendMemo.js";
 export const observer = runtimeObserver;

package/dist/orm/dataTree.js

@@ -178,14 +178,14 @@ export async function setPublicDoc(segments, value, deleteValue = false) {
     if (isIdFieldPath(segments, idFields))
         return;
     const doc = getConnection().get(collection, docId);
-    let docState = resolvePublicDocState({ collection, docId, doc, idFields, hydrateCompatDocData: true });
+    let docState = resolvePublicDocState({ collection, docId, doc, idFields, hydrateDocDataFromLocal: true });
     if (!docState.exists && segments.length > 2) {
-        docState = await resolvePublicDocStateWithCompatFetchFallback({
+        docState = await resolvePublicDocStateWithFetchFallback({
             collection,
             docId,
             doc,
             idFields,
-            hydrateCompatDocData: true
+            hydrateDocDataFromLocal: true
         });
     }
     if (!docState.exists && deleteValue)
@@ -286,14 +286,14 @@ export async function setPublicDocReplace(segments, value) {
     if (isIdFieldPath(segments, idFields))
         return;
     const doc = getConnection().get(collection, docId);
-    let docState = resolvePublicDocState({ collection, docId, doc, idFields, hydrateCompatDocData: true });
+    let docState = resolvePublicDocState({ collection, docId, doc, idFields, hydrateDocDataFromLocal: true });
     if (!docState.exists && segments.length > 2) {
-        docState = await resolvePublicDocStateWithCompatFetchFallback({
+        docState = await resolvePublicDocStateWithFetchFallback({
             collection,
             docId,
             doc,
             idFields,
-            hydrateCompatDocData: true
+            hydrateDocDataFromLocal: true
         });
     }
     // make sure that the value is not observable to not trigger extra reads. And clone it
@@ -374,9 +374,10 @@ async function createPublicDocAndHydrateLocal({ doc, collection, docId, newDoc,
     await new Promise((resolve, reject) => {
         doc.create(newDoc, err => err ? reject(err) : resolve());
     });
-    // In compatibility mode we must allow immediate subpath writes after create()
-    // even when the ShareDB snapshot hasn't been loaded via subscribe/fetch yet.
-    if (isCompatEnv() && doc?.data == null) {
+    // Keep public creates immediately writable even when the ShareDB snapshot has
+    // not been loaded via subscribe/fetch yet. UI flows rely on optimistic add()
+    // followed by child writes without waiting for DB confirmation.
+    if (doc?.data == null) {
         const localDoc = JSON.parse(JSON.stringify(newDoc || {}));
         if (isPlainObject(localDoc))
             injectIdFields(localDoc, idFields, docId);
@@ -387,7 +388,7 @@ async function createPublicDocAndHydrateLocal({ doc, collection, docId, newDoc,
     }
     ensureLocalDocSyncedWithShareDoc({ collection, docId, doc, idFields });
 }
-function resolvePublicDocState({ collection, docId, doc, idFields, hydrateCompatDocData = false }) {
+function resolvePublicDocState({ collection, docId, doc, idFields, hydrateDocDataFromLocal = false }) {
     ensureLocalDocSyncedWithShareDoc({ collection, docId, doc, idFields });
     if (isMissingShareDoc(doc)) {
         return { exists: false, snapshot: undefined, source: 'none' };
@@ -400,24 +401,29 @@ function resolvePublicDocState({ collection, docId, doc, idFields, hydrateCompat
         };
     }
     const localSnapshot = getRaw([collection, docId]);
-    if (!(isCompatEnv() && localSnapshot != null)) {
+    if (localSnapshot == null) {
         return { exists: false, snapshot: undefined, source: 'none' };
     }
-    // In compat mode local raw data can be the source of truth between create/add
-    // and later subpath mutations even if ShareDB doc.data is currently empty.
-    if (hydrateCompatDocData) {
+    // Local raw data can be the source of truth between add() and later subpath
+    // mutations even if ShareDB doc.data is currently empty or was recreated.
+    if (hydrateDocDataFromLocal) {
         doc.data = localSnapshot;
     }
     return { exists: true, snapshot: localSnapshot, source: 'local' };
 }
-async function resolvePublicDocStateWithCompatFetchFallback({ collection, docId, doc, idFields, hydrateCompatDocData = false }) {
-    let docState = resolvePublicDocState({ collection, docId, doc, idFields, hydrateCompatDocData });
-    if (docState.exists || !isCompatEnv())
+async function resolvePublicDocStateWithFetchFallback({ collection, docId, doc, idFields, hydrateDocDataFromLocal = false }) {
+    let docState = resolvePublicDocState({ collection, docId, doc, idFields, hydrateDocDataFromLocal });
+    if (docState.exists)
+        return docState;
+    const shouldFetch = isCompatEnv() || (getRaw([collection, docId]) != null &&
+        isMissingShareDoc(doc) &&
+        doc.version == null);
+    if (!shouldFetch)
         return docState;
     await new Promise((resolve, reject) => {
         doc.fetch(err => err ? reject(err) : resolve());
     });
-    docState = resolvePublicDocState({ collection, docId, doc, idFields, hydrateCompatDocData });
+    docState = resolvePublicDocState({ collection, docId, doc, idFields, hydrateDocDataFromLocal });
     return docState;
 }
 function ensureLocalDocSyncedWithShareDoc({ collection, docId, doc, idFields }) {
@@ -572,12 +578,12 @@ export async function incrementPublic(segments, byNumber) {
         throw Error(ERRORS.publicDoc(segments));
     const doc = getConnection().get(collection, docId);
     const idFields = getIdFieldsForSegments([collection, docId]);
-    const docState = await resolvePublicDocStateWithCompatFetchFallback({
+    const docState = await resolvePublicDocStateWithFetchFallback({
         collection,
         docId,
         doc,
         idFields,
-        hydrateCompatDocData: true
+        hydrateDocDataFromLocal: true
     });
     if (!docState.exists)
         throw Error(ERRORS.nonExistingDoc(segments));
@@ -615,12 +621,12 @@ export async function arrayInsertPublic(segments, index, values) {
         throw Error(ERRORS.publicDoc(segments));
     const doc = getConnection().get(collection, docId);
     const idFields = getIdFieldsForSegments([collection, docId]);
-    const docState = await resolvePublicDocStateWithCompatFetchFallback({
+    const docState = await resolvePublicDocStateWithFetchFallback({
         collection,
         docId,
         doc,
         idFields,
-        hydrateCompatDocData: true
+        hydrateDocDataFromLocal: true
     });
     if (!docState.exists)
         throw Error(ERRORS.nonExistingDoc(segments));
@@ -674,12 +680,12 @@ export async function arrayRemovePublic(segments, index, howMany = 1) {
         throw Error(ERRORS.publicDoc(segments));
     const doc = getConnection().get(collection, docId);
     const idFields = getIdFieldsForSegments([collection, docId]);
-    const docState = await resolvePublicDocStateWithCompatFetchFallback({
+    const docState = await resolvePublicDocStateWithFetchFallback({
         collection,
         docId,
         doc,
         idFields,
-        hydrateCompatDocData: true
+        hydrateDocDataFromLocal: true
     });
     if (!docState.exists)
         throw Error(ERRORS.nonExistingDoc(segments));
@@ -702,12 +708,12 @@ export async function arrayMovePublic(segments, from, to, howMany = 1) {
         throw Error(ERRORS.publicDoc(segments));
     const doc = getConnection().get(collection, docId);
     const idFields = getIdFieldsForSegments([collection, docId]);
-    const docState = await resolvePublicDocStateWithCompatFetchFallback({
+    const docState = await resolvePublicDocStateWithFetchFallback({
         collection,
         docId,
         doc,
         idFields,
-        hydrateCompatDocData: true
+        hydrateDocDataFromLocal: true
     });
     if (!docState.exists)
         throw Error(ERRORS.nonExistingDoc(segments));
@@ -780,12 +786,12 @@ export async function stringInsertPublic(segments, index, text) {
         throw Error(ERRORS.publicDoc(segments));
     const doc = getConnection().get(collection, docId);
     const idFields = getIdFieldsForSegments([collection, docId]);
-    const docState = await resolvePublicDocStateWithCompatFetchFallback({
+    const docState = await resolvePublicDocStateWithFetchFallback({
         collection,
         docId,
         doc,
         idFields,
-        hydrateCompatDocData: true
+        hydrateDocDataFromLocal: true
     });
     if (!docState.exists)
         throw Error(ERRORS.nonExistingDoc(segments));
@@ -814,12 +820,12 @@ export async function stringRemovePublic(segments, index, howMany) {
         throw Error(ERRORS.publicDoc(segments));
     const doc = getConnection().get(collection, docId);
     const idFields = getIdFieldsForSegments([collection, docId]);
-    const docState = await resolvePublicDocStateWithCompatFetchFallback({
+    const docState = await resolvePublicDocStateWithFetchFallback({
         collection,
         docId,
         doc,
         idFields,
-        hydrateCompatDocData: true
+        hydrateDocDataFromLocal: true
     });
     if (!docState.exists)
         throw Error(ERRORS.nonExistingDoc(segments));

package/dist/orm/sub.d.ts

@@ -1,40 +1,44 @@
 import type { AggregationFunction, AggregationParams, ClientAggregationFunction } from '@teamplay/utils/aggregation';
 import type { CollectionSignal, ComputedQueryParamsInput, DocumentSignal, MaybePromise, MaybePromiseSubResult, QueryParams, RegisteredAggregationInput, SignalModelConstructor, SubResult, TypedAggregationInput, TypedAggregationSignal, WildcardSignalPath } from './Signal.js';
+export type SubMode = 'auto' | 'fetch' | 'subscribe';
+export interface SubOptions {
+    mode?: SubMode;
+}
 /**
  * Subscribe to an aggregation with explicit output typing outside React.
  * @param $aggregation Typed aggregation input.
  * @param params Parameters passed to the aggregation.
  */
-export default function sub<TDocument, TDocumentModel extends SignalModelConstructor<TDocument>>($aggregation: TypedAggregationInput<TDocument, TDocumentModel>, params?: AggregationParams): MaybePromise<TypedAggregationSignal<TDocument, TDocumentModel>>;
+export default function sub<TDocument, TDocumentModel extends SignalModelConstructor<TDocument>>($aggregation: TypedAggregationInput<TDocument, TDocumentModel>, params?: AggregationParams, options?: SubOptions): MaybePromise<TypedAggregationSignal<TDocument, TDocumentModel>>;
 /**
  * Subscribe to a registered collection aggregation outside React.
  * @param $aggregation Aggregation header generated by StartupJS model loading.
  * @param params Parameters passed to the aggregation.
  */
-export default function sub<TCollection extends string, TOutput = unknown>($aggregation: RegisteredAggregationInput<TCollection, TOutput>, params?: AggregationParams): MaybePromise<SubResult<RegisteredAggregationInput<TCollection, TOutput>>>;
+export default function sub<TCollection extends string, TOutput = unknown>($aggregation: RegisteredAggregationInput<TCollection, TOutput>, params?: AggregationParams, options?: SubOptions): MaybePromise<SubResult<RegisteredAggregationInput<TCollection, TOutput>>>;
 /**
  * Subscribe to a client aggregation outside React.
  * @param $aggregation Aggregation function created with `aggregation(collection, fn)`.
  * @param params Parameters passed to the aggregation.
  */
-export default function sub<TOutput, TCollection extends string>($aggregation: ClientAggregationFunction<TOutput, TCollection>, params?: AggregationParams): MaybePromise<SubResult<ClientAggregationFunction<TOutput, TCollection>>>;
+export default function sub<TOutput, TCollection extends string>($aggregation: ClientAggregationFunction<TOutput, TCollection>, params?: AggregationParams, options?: SubOptions): MaybePromise<SubResult<ClientAggregationFunction<TOutput, TCollection>>>;
 /**
  * Subscribe to an unregistered aggregation outside React.
  * @param $aggregation Aggregation function.
  * @param params Parameters passed to the aggregation.
  */
-export default function sub<TOutput = unknown, TCollection extends string = string>($aggregation: AggregationFunction<TOutput, TCollection>, params?: AggregationParams): MaybePromise<SubResult<AggregationFunction<TOutput, TCollection>>>;
+export default function sub<TOutput = unknown, TCollection extends string = string>($aggregation: AggregationFunction<TOutput, TCollection>, params?: AggregationParams, options?: SubOptions): MaybePromise<SubResult<AggregationFunction<TOutput, TCollection>>>;
 /**
  * Subscribe to a document signal outside React and return it when ready.
  * @param $signal Document signal to subscribe to.
  */
-export default function sub<TSignal extends DocumentSignal<any, any, any>>($signal: TSignal): MaybePromiseSubResult<TSignal>;
+export default function sub<TSignal extends DocumentSignal<any, any, any>>($signal: TSignal, options?: SubOptions): MaybePromiseSubResult<TSignal>;
 /**
  * Subscribe to a collection query outside React and return a query signal when ready.
  * @param $collection Collection signal to query.
  * @param params Mongo-style query params, including filters and `$sort`.
  */
-export default function sub<TDocument, TCollectionModel extends SignalModelConstructor<TDocument[]>, TDocumentModel extends SignalModelConstructor<TDocument>, TCollectionPath extends WildcardSignalPath>($collection: CollectionSignal<TDocument, TCollectionModel, TDocumentModel, TCollectionPath>, params: QueryParams<TDocument>): MaybePromiseSubResult<CollectionSignal<TDocument, TCollectionModel, TDocumentModel, TCollectionPath>, QueryParams<TDocument>>;
+export default function sub<TDocument, TCollectionModel extends SignalModelConstructor<TDocument[]>, TDocumentModel extends SignalModelConstructor<TDocument>, TCollectionPath extends WildcardSignalPath>($collection: CollectionSignal<TDocument, TCollectionModel, TDocumentModel, TCollectionPath>, params: QueryParams<TDocument>, options?: SubOptions): MaybePromiseSubResult<CollectionSignal<TDocument, TCollectionModel, TDocumentModel, TCollectionPath>, QueryParams<TDocument>>;
 /**
  * Subscribe to a collection query with computed string keys outside React.
  * This fallback preserves Mongo-style computed paths such as `{ [`likes.${id}`]: true }`.
@@ -42,4 +46,5 @@ export default function sub<TDocument, TCollectionModel extends SignalModelConst
  * @param $collection Collection signal to query.
  * @param params Mongo-style query params with a widened computed key.
  */
-export default function sub<TDocument, TCollectionModel extends SignalModelConstructor<TDocument[]>, TDocumentModel extends SignalModelConstructor<TDocument>, TCollectionPath extends WildcardSignalPath, TParams extends object>($collection: CollectionSignal<TDocument, TCollectionModel, TDocumentModel, TCollectionPath>, params: TParams & ComputedQueryParamsInput<TParams>): MaybePromiseSubResult<CollectionSignal<TDocument, TCollectionModel, TDocumentModel, TCollectionPath>, TParams>;
+export default function sub<TDocument, TCollectionModel extends SignalModelConstructor<TDocument[]>, TDocumentModel extends SignalModelConstructor<TDocument>, TCollectionPath extends WildcardSignalPath, TParams extends object>($collection: CollectionSignal<TDocument, TCollectionModel, TDocumentModel, TCollectionPath>, params: TParams & ComputedQueryParamsInput<TParams>, options?: SubOptions): MaybePromiseSubResult<CollectionSignal<TDocument, TCollectionModel, TDocumentModel, TCollectionPath>, TParams>;
+export declare function unsub($signal: unknown): Promise<void> | void;

package/dist/orm/sub.js

@@ -3,9 +3,11 @@ import Signal, { SEGMENTS, isPublicCollectionSignal, isPublicDocumentSignal } fr
 import { docSubscriptions } from './Doc.js';
 import { querySubscriptions, getQuerySignal } from './Query.js';
 import { aggregationSubscriptions, getAggregationSignal } from './Aggregation.js';
-import { getRoot } from "./Root.js";
+import { getRoot, ROOT_ID } from "./Root.js";
+import { isRootContextClosed } from "./rootContext.js";
 import isServer from "../utils/isServer.js";
-export default function sub($signal, params) {
+const SUB_RECORDS = new WeakMap();
+export default function sub($signal, params, options) {
     // TODO: temporarily disable support for multiple subscriptions
     //       since this has to be properly cached using useDeferredSignal() in useSub()
     // if (Array.isArray($signal)) {
@@ -16,26 +18,26 @@ export default function sub($signal, params) {
     if (Array.isArray($signal))
         throw Error('sub() does not support multiple subscriptions yet');
     if (isRuntimePublicDocumentSignal($signal)) {
-        if (arguments.length > 1) {
+        if (arguments.length > 2) {
             throw Error(ERRORS.subDocArguments($signal, ...Array.from(arguments).slice(1)));
         }
-        return doc$($signal);
+        return doc$($signal, parseSubOptions(params));
     }
     else if (isRuntimePublicCollectionSignal($signal)) {
-        if (arguments.length !== 2) {
+        if (arguments.length < 2 || arguments.length > 3) {
             throw Error(ERRORS.subQueryArguments($signal, params, ...Array.from(arguments).slice(2)));
         }
-        return query$($signal, params);
+        return query$($signal, params, parseSubOptions(options));
     }
     else if (isClientAggregationFunction($signal)) {
-        return getAggregationFromFunction($signal, $signal.collection, params);
+        return getAggregationFromFunction($signal, $signal.collection, params, parseSubOptions(options));
     }
     else if (isAggregationHeader($signal)) {
         const aggregationParams = {
             $aggregationName: $signal.name,
             $params: sanitizeAggregationParams(params)
         };
-        return aggregation$($signal.collection, aggregationParams);
+        return aggregation$($signal.collection, aggregationParams, undefined, parseSubOptions(options));
     }
     else if (isAggregationFunction($signal)) {
         if (isServer) {
@@ -46,7 +48,7 @@ export default function sub($signal, params) {
             }
             const aggregationParams = { ...serverParams };
             delete aggregationParams.$collection;
-            return getAggregationFromFunction($signal, collection, aggregationParams);
+            return getAggregationFromFunction($signal, collection, aggregationParams, parseSubOptions(options));
         }
         else {
             throw Error(ERRORS.gotAggregationFunction($signal));
@@ -59,7 +61,25 @@ export default function sub($signal, params) {
         throw Error('Invalid args passed for sub()');
     }
 }
-function getAggregationFromFunction(fn, collection, params) {
+export function unsub($signal) {
+    if (!($signal instanceof Signal))
+        return;
+    const record = takeSubRecord($signal);
+    if (!record)
+        return;
+    record.disposed = true;
+    const $root = getRoot($signal);
+    const rootId = $root?.[ROOT_ID];
+    if (isRootContextClosed(rootId))
+        return;
+    if (record.kind === 'doc')
+        return docSubscriptions.unsubscribe($signal, { intent: record.intent });
+    if (record.kind === 'query')
+        return querySubscriptions.unsubscribe($signal, { intent: record.intent });
+    if (record.kind === 'aggregation')
+        return aggregationSubscriptions.unsubscribe($signal, { intent: record.intent });
+}
+function getAggregationFromFunction(fn, collection, params, subOptions) {
     const aggregationParams = sanitizeAggregationParams(params);
     let session;
     if (isRecord(aggregationParams) && aggregationParams.$session) {
@@ -70,15 +90,13 @@ function getAggregationFromFunction(fn, collection, params) {
     // should match the context in @teamplay/backend/features/serverAggregate.js
     const context = { collection, session, isServer };
     const result = fn(aggregationParams, context);
-    return aggregation$(collection, Array.isArray(result) ? { $aggregate: result } : result);
+    return aggregation$(collection, Array.isArray(result) ? { $aggregate: result } : result, undefined, subOptions);
 }
-function doc$($doc) {
-    const promise = docSubscriptions.subscribe($doc);
-    if (!promise)
-        return $doc;
-    return new Promise(resolve => promise.then(() => resolve($doc)));
+function doc$($doc, subOptions) {
+    const promise = docSubscriptions.subscribe($doc, { intent: subOptions.intent });
+    return returnSubscribedSignal($doc, 'doc', subOptions.intent, promise);
 }
-function query$($collection, params) {
+function query$($collection, params, subOptions) {
     const collectionName = $collection[SEGMENTS][0];
     if (typeof collectionName !== 'string')
         throw Error(ERRORS.queryCollectionName($collection));
@@ -86,20 +104,17 @@ function query$($collection, params) {
         throw Error(ERRORS.queryParamsObject(collectionName, params));
     const signalOptions = getQuerySignalOptions($collection);
     const queryParams = params;
-    if (queryParams?.$aggregate || queryParams?.$aggregationName)
-        return aggregation$(collectionName, params, signalOptions);
+    if (queryParams?.$aggregate || queryParams?.$aggregationName) {
+        return aggregation$(collectionName, params, signalOptions, subOptions);
+    }
     const $query = getQuerySignal(collectionName, params, signalOptions);
-    const promise = querySubscriptions.subscribe($query);
-    if (!promise)
-        return $query;
-    return new Promise(resolve => promise.then(() => resolve($query)));
+    const promise = querySubscriptions.subscribe($query, { intent: subOptions.intent });
+    return returnSubscribedSignal($query, 'query', subOptions.intent, promise);
 }
-function aggregation$(collectionName, params, signalOptions) {
+function aggregation$(collectionName, params, signalOptions, subOptions = parseSubOptions()) {
     const $aggregationQuery = getAggregationSignal(collectionName, params, signalOptions);
-    const promise = aggregationSubscriptions.subscribe($aggregationQuery);
-    if (!promise)
-        return $aggregationQuery;
-    return new Promise(resolve => promise.then(() => resolve($aggregationQuery)));
+    const promise = aggregationSubscriptions.subscribe($aggregationQuery, { intent: subOptions.intent });
+    return returnSubscribedSignal($aggregationQuery, 'aggregation', subOptions.intent, promise);
 }
 function api$(_fn, _args) {
     throw Error('sub() for async functions is not implemented yet');
@@ -133,14 +148,56 @@ function isRuntimePublicCollectionSignal(value) {
 function isApiFunction(value) {
     return typeof value === 'function' && !(value instanceof Signal);
 }
+function parseSubOptions(options) {
+    const mode = options?.mode ?? 'auto';
+    if (mode !== 'auto' && mode !== 'fetch' && mode !== 'subscribe') {
+        throw Error(`sub() option mode must be "auto", "fetch", or "subscribe". Got: ${mode}`);
+    }
+    return {
+        intent: mode === 'fetch' ? 'fetch' : 'subscribe'
+    };
+}
+function returnSubscribedSignal($signal, kind, intent, promise) {
+    if (!promise) {
+        addSubRecord($signal, kind, intent);
+        return $signal;
+    }
+    return promise.then(() => {
+        addSubRecord($signal, kind, intent);
+        return $signal;
+    });
+}
+function addSubRecord($signal, kind, intent) {
+    let records = SUB_RECORDS.get($signal);
+    if (!records) {
+        records = [];
+        SUB_RECORDS.set($signal, records);
+    }
+    records.push({ kind, intent, disposed: false });
+}
+function takeSubRecord($signal) {
+    const records = SUB_RECORDS.get($signal);
+    if (!records)
+        return;
+    for (let i = records.length - 1; i >= 0; i--) {
+        const record = records[i];
+        if (record.disposed)
+            continue;
+        records.splice(i, 1);
+        if (records.length === 0)
+            SUB_RECORDS.delete($signal);
+        return record;
+    }
+    SUB_RECORDS.delete($signal);
+}
 const ERRORS = {
     subDocArguments: ($signal, ...args) => `
-    sub($doc) accepts only 1 argument - the document signal to subscribe to
+    sub($doc) accepts one or two arguments - the document signal and optional options.
     Doc: ${$signal[SEGMENTS]}
     Got args: ${[$signal, ...args]}
   `,
     subQueryArguments: ($signal, params, ...args) => `
-    sub($collection, params) accepts 2 arguments - the collection signal and an object with query params.
+    sub($collection, params) accepts two or three arguments - the collection signal, query params, and optional options.
     If you want to subscribe to all documents in a collection, pass an empty object: sub($collection, {}).
     Collection: ${$signal[SEGMENTS]}
     Params: ${params}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teamplay",
-  "version": "0.5.0-alpha.24",
+  "version": "0.5.0-alpha.26",
   "description": "Full-stack signals ORM with multiplayer",
   "type": "module",
   "main": "./dist/index.js",
@@ -134,5 +134,5 @@
     ]
   },
   "license": "MIT",
-  "gitHead": "cdb8848af9b1f3ecc77e990a3fbc4d55d4aa0dec"
+  "gitHead": "a432e1c1dc272cfe2b87e3820557db4721a0f38b"
 }