teamplay 0.5.0-alpha.25 → 0.5.0-alpha.27

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/Compat/SignalCompat.js

@@ -1,7 +1,7 @@
 import { raw, observe, unobserve } from '@nx-js/observer-util';
 import arrayDiff from 'arraydiff';
 import { Signal, GETTERS, DEFAULT_GETTERS, SEGMENTS, isPublicCollection, isPublicCollectionSignal, isPublicDocumentSignal } from "../SignalBase.js";
-import { getRoot, ROOT, ROOT_ID, getRootSignal, GLOBAL_ROOT_ID, unregisterRootFinalizer } from "../Root.js";
+import { getRoot, ROOT, ROOT_ID, getRootSignal, GLOBAL_ROOT_ID } from "../Root.js";
 import { docSubscriptions } from '../Doc.js';
 import { IS_QUERY, getQuerySignal, querySubscriptions } from '../Query.js';
 import { AGGREGATIONS, IS_AGGREGATION, aggregationSubscriptions, getAggregationSignal } from '../Aggregation.js';
@@ -16,7 +16,6 @@ import { runInBatch } from '../batchScheduler.js';
 import { runInSilentContext, runInModelEventsSilentContext, isSilentContextActive } from './silentContext.js';
 import universal$ from "../../react/universal$.js";
 import { getRootContext } from "../rootContext.js";
-import disposeRootContext from "../disposeRootContext.js";
 import { arrayInsertPrivateData, arrayMovePrivateData, arrayPopPrivateData, arrayPushPrivateData, arrayRemovePrivateData, arrayShiftPrivateData, arrayUnshiftPrivateData, delPrivateData, setReplacePrivateData, stringInsertPrivateData, stringRemovePrivateData } from '../privateData.js';
 class SignalCompat extends Signal {
     static ID_FIELDS = ['_id', 'id'];
@@ -92,24 +91,6 @@ class SignalCompat extends Signal {
             return this.extra.get();
         return undefined;
     }
-    close(callback) {
-        if (arguments.length > 1)
-            throw Error('Signal.close() expects zero or one argument');
-        if (callback != null && typeof callback !== 'function') {
-            throw Error('Signal.close() expects callback to be a function');
-        }
-        const $root = getRoot(this) || this;
-        const rootId = $root?.[ROOT_ID];
-        unregisterRootFinalizer($root);
-        disposeRootContext(rootId)
-            .then(() => callback?.())
-            .catch(err => {
-            if (callback)
-                callback(err);
-            else
-                console.error(err);
-        });
-    }
     silent(value) {
         if (arguments.length > 1)
             throw Error('Signal.silent() expects zero or one argument');

package/dist/orm/Root.d.ts

@@ -14,8 +14,12 @@ export type RootSignalRuntime = SignalBaseInstance & {
     [ROOT]?: RootSignalRuntime;
     [ROOT_ID]?: string;
 };
+export type RootCloseCallback = (err?: unknown) => void;
 export declare function getRootSignal({ rootFunction, fetchOnly, rootId, ...options }?: RootSignalOptions): RootSignalRuntime;
 export declare function getRoot(signal: RootSignalRuntime | undefined): RootSignalRuntime | undefined;
+export declare function closeRootSignalAsync(signal: RootSignalRuntime | undefined): Promise<void>;
+export declare function closeRootSignal(signal: RootSignalRuntime | undefined): Promise<void>;
+export declare function closeRootSignal(signal: RootSignalRuntime | undefined, callback?: RootCloseCallback): void;
 export declare function getRootFetchOnly(rootOrRootId: RootSignalRuntime | string | undefined): boolean;
 export declare function getRootTransportMode(rootOrRootId: RootSignalRuntime | string | undefined, intent?: RootTransportIntent): RootTransportIntent;
 export declare function registerRootFinalizer($root: RootSignalRuntime | undefined): void;

package/dist/orm/Root.js

@@ -43,6 +43,22 @@ export function getRoot(signal) {
     else
         return undefined;
 }
+export function closeRootSignalAsync(signal) {
+    const $root = getRoot(signal) || signal;
+    const rootId = $root?.[ROOT_ID];
+    unregisterRootFinalizer($root);
+    return disposeRootContext(rootId);
+}
+export function closeRootSignal(signal, callback) {
+    const promise = closeRootSignalAsync(signal);
+    if (!callback)
+        return promise;
+    promise
+        .then(() => callback?.())
+        .catch(err => {
+        callback(err);
+    });
+}
 export function getRootFetchOnly(rootOrRootId) {
     const $root = typeof rootOrRootId === 'string'
         ? undefined

package/dist/orm/SignalBase.d.ts

@@ -45,6 +45,8 @@ export declare class Signal<TValue = unknown> extends Function {
      * @param fn Function to execute inside the batch.
      */
     batch<TResult>(fn: () => TResult): TResult;
+    close(): Promise<void>;
+    close(callback: (err?: unknown) => void): void;
     /**
      * Internal read hook used by `.get()` and `.peek()`.
      * @param method Storage read function to use for the current signal path.

package/dist/orm/SignalBase.js

@@ -20,7 +20,7 @@ import getSignal, { rawSignal } from "./getSignal.js";
 import { docSubscriptions } from './Doc.js';
 import { IS_QUERY, HASH, QUERIES } from './Query.js';
 import { AGGREGATIONS, IS_AGGREGATION, getAggregationCollectionName, getAggregationDocId } from './Aggregation.js';
-import { ROOT_FUNCTION, ROOT_ID, getRoot } from "./Root.js";
+import { ROOT_FUNCTION, ROOT_ID, closeRootSignal, getRoot } from "./Root.js";
 import { DEFAULT_ID_FIELDS, getIdFieldsForSegments, isIdFieldPath, isPlainObject, isPublicDocPath, normalizeIdFields, prepareAddPayload, resolveAddDocId } from "./idFields.js";
 import { isCompatEnv } from './compatEnv.js';
 import { resolveRefSegmentsSafe, resolveRefSignalSafe } from './Compat/refFallback.js';
@@ -181,6 +181,14 @@ export class Signal extends Function {
             throw Error('Signal.batch() expects a function argument');
         return runInBatch(fn);
     }
+    close(callback) {
+        if (arguments.length > 1)
+            throw Error('Signal.close() expects zero or one argument');
+        if (callback != null && typeof callback !== 'function') {
+            throw Error('Signal.close() expects callback to be a function');
+        }
+        return callback ? closeRootSignal(this, callback) : closeRootSignal(this);
+    }
     /**
      * Internal read hook used by `.get()` and `.peek()`.
      * @param method Storage read function to use for the current signal path.

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.25",
+  "version": "0.5.0-alpha.27",
   "description": "Full-stack signals ORM with multiplayer",
   "type": "module",
   "main": "./dist/index.js",
@@ -134,5 +134,5 @@
     ]
   },
   "license": "MIT",
-  "gitHead": "f1dcc0b025c80535acfe03a583e828c491f2a1e6"
+  "gitHead": "cbdbd79ede32eab577708675ab7a50c205bed50b"
 }