teamplay 0.5.0-alpha.9 → 0.5.0

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/dist/orm/subscriptionGcDelay.js

@@ -1,6 +1,4 @@
-import { isCompatEnv } from './compatEnv.js';
-const DEFAULT_COMPAT_SUBSCRIPTION_GC_DELAY = 3000;
-const DEFAULT_SUBSCRIPTION_GC_DELAY = 0;
+const DEFAULT_SUBSCRIPTION_GC_DELAY = 3000;
 let subscriptionGcDelay = getDefaultSubscriptionGcDelay();
 export function getSubscriptionGcDelay() {
     return subscriptionGcDelay;
@@ -17,9 +15,7 @@ export function setSubscriptionGcDelay(ms) {
     return subscriptionGcDelay;
 }
 export function getDefaultSubscriptionGcDelay() {
-    return isCompatEnv()
-        ? DEFAULT_COMPAT_SUBSCRIPTION_GC_DELAY
-        : DEFAULT_SUBSCRIPTION_GC_DELAY;
+    return DEFAULT_SUBSCRIPTION_GC_DELAY;
 }
 export function __resetSubscriptionGcDelayForTests() {
     subscriptionGcDelay = getDefaultSubscriptionGcDelay();

package/dist/react/convertToObserver.js

@@ -7,7 +7,6 @@ import executionContextTracker from "./executionContextTracker.js";
 import { pipeComponentMeta, useUnmount, useId, useTriggerUpdate } from "./helpers.js";
 import trapRender from './trapRender.js';
 import { scheduleReaction } from '../orm/batchScheduler.js';
-import { isCompatComponent, unmarkCompatComponent } from "./compatComponentRegistry.js";
 const DEFAULT_THROTTLE_TIMEOUT = 100;
 export default function convertToObserver(BaseComponent, { forwardRef, cache: enableCache = true, throttle, ...options } = {}) {
     throttle = normalizeThrottle(throttle);
@@ -33,7 +32,7 @@ export default function convertToObserver(BaseComponent, { forwardRef, cache: en
                     hasDeferredUpdateAfterExecutionContext = false;
                     triggerUpdate();
                 }
-                else if (isCompatComponent(componentId)) {
+                else {
                     if (hasDeferredUpdateAfterExecutionContext)
                         return;
                     hasDeferredUpdateAfterExecutionContext = true;
@@ -53,7 +52,6 @@ export default function convertToObserver(BaseComponent, { forwardRef, cache: en
                 if (!reactionRef.current)
                     throw Error(`NO REACTION REF - ${where}`);
                 destroyRef.current = undefined;
-                unmarkCompatComponent(componentId);
                 unobserve(reactionRef.current);
                 reactionRef.current = undefined;
                 destroyCache(where);
@@ -71,7 +69,6 @@ export default function convertToObserver(BaseComponent, { forwardRef, cache: en
         }
         // clean up observer on unmount
         useUnmount(() => {
-            unmarkCompatComponent(componentId);
             destroyRef.current?.('useUnmount()');
         });
         return reactionRef.current(...args);

package/dist/react/promiseBatcher.js

@@ -95,7 +95,7 @@ function warnAboutChecksDelay(checks) {
             state
         };
     });
-    console.warn('[teamplay] useBatch() is waiting for data materialization checks.', details);
+    console.warn('[teamplay] useBatchSub() is waiting for data materialization checks.', details);
 }
 function isDevMode() {
     const processLike = globalThis.process;

package/dist/react/renderAttemptDestroyer.d.ts

@@ -1,17 +1,9 @@
-type DestroyAttempt = () => unknown | Promise<unknown>;
 declare class RenderAttemptDestroyer {
-    fns: DestroyAttempt[];
-    compatAttemptCleanupArmed: boolean;
     suspenseGateArmed: boolean;
     constructor();
-    add(fn: DestroyAttempt | undefined, { compat }?: {
-        compat?: boolean;
-    }): void;
-    armCompatAttemptCleanup(): void;
     armSuspenseGate(): void;
     consumeThenableHandling(): {
         shouldKeepShellAlive: boolean;
-        destroyAttempt?: () => Promise<void>;
     };
     reset(): void;
 }

package/dist/react/renderAttemptDestroyer.js

@@ -1,45 +1,19 @@
 class RenderAttemptDestroyer {
-    fns;
-    compatAttemptCleanupArmed;
     suspenseGateArmed;
     constructor() {
-        this.fns = [];
-        this.compatAttemptCleanupArmed = false;
         this.suspenseGateArmed = false;
     }
-    add(fn, { compat = false } = {}) {
-        if (typeof fn !== 'function')
-            return;
-        this.fns.push(fn);
-        if (compat)
-            this.compatAttemptCleanupArmed = true;
-    }
-    armCompatAttemptCleanup() {
-        this.compatAttemptCleanupArmed = true;
-    }
     armSuspenseGate() {
         this.suspenseGateArmed = true;
     }
     consumeThenableHandling() {
-        const shouldRunAttemptCleanup = this.compatAttemptCleanupArmed && this.fns.length > 0;
-        const shouldKeepShellAlive = this.suspenseGateArmed || shouldRunAttemptCleanup;
-        let destroyAttempt;
-        if (shouldRunAttemptCleanup) {
-            const fns = [...this.fns];
-            destroyAttempt = async () => {
-                await Promise.allSettled(fns.map(fn => fn()));
-                fns.length = 0;
-            };
-        }
+        const shouldKeepShellAlive = this.suspenseGateArmed;
         this.reset();
         return {
-            shouldKeepShellAlive,
-            destroyAttempt
+            shouldKeepShellAlive
         };
     }
     reset() {
-        this.fns.length = 0;
-        this.compatAttemptCleanupArmed = false;
         this.suspenseGateArmed = false;
     }
 }

package/dist/react/trapRender.js

@@ -13,7 +13,7 @@ export default function trapRender({ render, cache, destroy, componentId }) {
             promiseBatcher.reset();
             const res = render(...args);
             if (isDevMode() && promiseBatcher.isActive()) {
-                throw Error('[teamplay] useBatch* hooks were used without a closing useBatch() call.');
+                throw Error('[teamplay] batch subscriptions were used without a closing useBatchSub() call or useSub(undefined, undefined, { batch: true }) call.');
             }
             return res;
         }
@@ -24,9 +24,9 @@ export default function trapRender({ render, cache, destroy, componentId }) {
                 destroyed = true;
                 throw err;
             }
-            const { shouldKeepShellAlive, destroyAttempt } = renderAttemptDestroyer.consumeThenableHandling();
+            const { shouldKeepShellAlive } = renderAttemptDestroyer.consumeThenableHandling();
             if (shouldKeepShellAlive) {
-                throw Promise.resolve(err).then(() => destroyAttempt?.());
+                throw Promise.resolve(err);
             }
             // TODO: this might only be needed only if promise is thrown
             //       (check if useUnmount in convertToObserver is called if a regular error is thrown)

package/dist/react/useSub.d.ts

@@ -1,5 +1,5 @@
 import type { AggregationFunction, AggregationParams, ClientAggregationFunction } from '@teamplay/utils/aggregation';
-import type { CollectionSignal, ComputedQueryParamsInput, DocumentSignal, QueryParams, RegisteredAggregationInput, SignalModelConstructor, SubResult, TypedAggregationInput, TypedAggregationSignal, WildcardSignalPath } from '../orm/Signal.js';
+import { type CollectionSignal, type ComputedQueryParamsInput, type DocumentSignal, type QueryParams, type RegisteredAggregationInput, type SignalModelConstructor, type SubResult, type TypedAggregationInput, type TypedAggregationSignal, type WildcardSignalPath } from '../orm/Signal.js';
 export interface UseSubOptions {
     /** Return `undefined` while loading instead of throwing a Suspense promise. */
     async?: boolean;
@@ -7,9 +7,14 @@ export interface UseSubOptions {
     defer?: boolean | number;
     /** Batch Suspense promises across multiple subscriptions in one render attempt. */
     batch?: boolean;
-    /** Enable compatibility cleanup for legacy observer render attempts. */
-    compatAttemptCleanup?: boolean;
 }
+/**
+ * Subscribe to a document signal in React async mode.
+ * @param signal Document signal to subscribe to.
+ * @param params Must be omitted for document subscriptions.
+ * @param options Subscription behavior options.
+ */
+export declare function useAsyncSub<TSignal extends DocumentSignal<any, any, any>>(signal: TSignal, options?: UseSubOptions): SubResult<TSignal>;
 /**
  * Subscribe to a document signal in React async mode.
  * @param signal Document signal to subscribe to.
@@ -61,6 +66,82 @@ export declare function useAsyncSub<TDocument, TDocumentModel extends SignalMode
  * @param options Subscription behavior options.
  */
 export declare function useAsyncSub<TOutput = unknown, TCollection extends string = string>(signal: AggregationFunction<TOutput, TCollection>, params?: AggregationParams, options?: UseSubOptions): SubResult<AggregationFunction<TOutput, TCollection>, AggregationParams | undefined>;
+/**
+ * Close a batch subscription barrier opened by previous `useBatchSub()` calls in this render.
+ */
+export declare function useBatchSub(): void;
+/**
+ * Subscribe to a document signal in React batch mode.
+ * @param signal Document signal to subscribe to.
+ * @param params Must be omitted for document subscriptions.
+ * @param options Subscription behavior options.
+ */
+export declare function useBatchSub<TSignal extends DocumentSignal<any, any, any>>(signal: TSignal, options?: UseSubOptions): SubResult<TSignal>;
+/**
+ * Subscribe to a document signal in React batch mode.
+ * @param signal Document signal to subscribe to.
+ * @param params Must be omitted for document subscriptions.
+ * @param options Subscription behavior options.
+ */
+export declare function useBatchSub<TSignal extends DocumentSignal<any, any, any>>(signal: TSignal, params?: undefined, options?: UseSubOptions): SubResult<TSignal>;
+/**
+ * Subscribe to a collection query in React batch mode.
+ * @param signal Collection signal to query.
+ * @param params Mongo-style query params, including filters and `$sort`.
+ * @param options Subscription behavior options.
+ */
+export declare function useBatchSub<TDocument, TCollectionModel extends SignalModelConstructor<TDocument[]>, TDocumentModel extends SignalModelConstructor<TDocument>, TCollectionPath extends WildcardSignalPath>(signal: CollectionSignal<TDocument, TCollectionModel, TDocumentModel, TCollectionPath>, params: QueryParams<TDocument>, options?: UseSubOptions): SubResult<CollectionSignal<TDocument, TCollectionModel, TDocumentModel, TCollectionPath>, QueryParams<TDocument>>;
+/**
+ * Subscribe to a collection query with computed string keys in React batch mode.
+ * This fallback preserves Mongo-style computed paths such as `{ [`likes.${id}`]: true }`.
+ * Literal query objects should use the stricter overload above.
+ * @param signal Collection signal to query.
+ * @param params Mongo-style query params with a widened computed key.
+ * @param options Subscription behavior options.
+ */
+export declare function useBatchSub<TDocument, TCollectionModel extends SignalModelConstructor<TDocument[]>, TDocumentModel extends SignalModelConstructor<TDocument>, TCollectionPath extends WildcardSignalPath, TParams extends object>(signal: CollectionSignal<TDocument, TCollectionModel, TDocumentModel, TCollectionPath>, params: TParams & ComputedQueryParamsInput<TParams>, options?: UseSubOptions): SubResult<CollectionSignal<TDocument, TCollectionModel, TDocumentModel, TCollectionPath>, TParams>;
+/**
+ * Subscribe to a registered collection aggregation in React batch mode.
+ * @param signal Aggregation header generated by StartupJS model loading.
+ * @param params Parameters passed to the aggregation.
+ * @param options Subscription behavior options.
+ */
+export declare function useBatchSub<TCollection extends string, TOutput = unknown>(signal: RegisteredAggregationInput<TCollection, TOutput>, params?: AggregationParams, options?: UseSubOptions): SubResult<RegisteredAggregationInput<TCollection, TOutput>>;
+/**
+ * Subscribe to a client aggregation in React batch mode.
+ * @param signal Aggregation function created with `aggregation(collection, fn)`.
+ * @param params Parameters passed to the aggregation.
+ * @param options Subscription behavior options.
+ */
+export declare function useBatchSub<TOutput, TCollection extends string>(signal: ClientAggregationFunction<TOutput, TCollection>, params?: AggregationParams, options?: UseSubOptions): SubResult<ClientAggregationFunction<TOutput, TCollection>>;
+/**
+ * Subscribe to an aggregation with explicit output typing in React batch mode.
+ * @param signal Typed aggregation input.
+ * @param params Parameters passed to the aggregation.
+ * @param options Subscription behavior options.
+ */
+export declare function useBatchSub<TDocument, TDocumentModel extends SignalModelConstructor<TDocument>>(signal: TypedAggregationInput<TDocument, TDocumentModel>, params?: AggregationParams, options?: UseSubOptions): TypedAggregationSignal<TDocument, TDocumentModel>;
+/**
+ * Subscribe to an unregistered aggregation in React batch mode.
+ * @param signal Aggregation function.
+ * @param params Parameters passed to the aggregation.
+ * @param options Subscription behavior options.
+ */
+export declare function useBatchSub<TOutput = unknown, TCollection extends string = string>(signal: AggregationFunction<TOutput, TCollection>, params?: AggregationParams, options?: UseSubOptions): SubResult<AggregationFunction<TOutput, TCollection>, AggregationParams | undefined>;
+/**
+ * Close a batch subscription barrier opened by previous `useSub(..., { batch: true })`
+ * calls in this render.
+ */
+export default function useSub(signal: undefined, params: undefined, options: UseSubOptions & {
+    batch: true;
+}): void;
+/**
+ * Subscribe to a document signal in React.
+ * @param signal Document signal to subscribe to.
+ * @param params Must be omitted for document subscriptions.
+ * @param options Subscription behavior options.
+ */
+export default function useSub<TSignal extends DocumentSignal<any, any, any>>(signal: TSignal, options?: UseSubOptions): SubResult<TSignal>;
 /**
  * Subscribe to a document signal in React.
  * @param signal Document signal to subscribe to.
@@ -112,8 +193,8 @@ export default function useSub<TDocument, TDocumentModel extends SignalModelCons
  * @param options Subscription behavior options.
  */
 export default function useSub<TOutput = unknown, TCollection extends string = string>(signal: AggregationFunction<TOutput, TCollection>, params?: AggregationParams, options?: UseSubOptions): SubResult<AggregationFunction<TOutput, TCollection>, AggregationParams | undefined>;
-export declare function useSubDeferred(signal: unknown, params?: unknown, { async, defer, batch, compatAttemptCleanup }?: UseSubOptions): unknown;
-export declare function useSubClassic(signal: unknown, params?: unknown, { async, batch, compatAttemptCleanup }?: UseSubOptions): unknown;
+export declare function useSubDeferred(signal: unknown, params?: unknown, { async, defer, batch }?: UseSubOptions): unknown;
+export declare function useSubClassic(signal: unknown, params?: unknown, { async, batch }?: UseSubOptions): unknown;
 export declare function setTestThrottling(ms: number): void;
 export declare function resetTestThrottling(): void;
 export declare function setUseDeferredValue(value: boolean): void;