teamplay 0.5.0-alpha.17 → 0.5.0-alpha.19

package/dist/index.d.ts

@@ -54,10 +54,9 @@ 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 useSub, useAsyncSub, setUseDeferredValue as __setUseDeferredValue, setDefaultDefer as __setDefaultDefer } from './react/useSub.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;
-export { useBatch, useBatchDoc, useBatchDoc$, useBatchQuery, useBatchQuery$, useBatchQueryIds, useBatchQueryDoc, useBatchQueryDoc$ } from './orm/Compat/hooksCompat.js';
 export { emit, useOn, useEmit } from './orm/Compat/eventsCompat.js';
 export { useDidUpdate, useOnce, useSyncEffect } from './react/helpers.js';
 export { connection, setConnection, getConnection, getDefaultFetchOnly, setDefaultFetchOnly, publicOnly, setPublicOnly } from './orm/connection.js';

package/dist/index.js

@@ -15,10 +15,9 @@ 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 useSub, useAsyncSub, setUseDeferredValue as __setUseDeferredValue, setDefaultDefer as __setDefaultDefer } from "./react/useSub.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;
-export { useBatch, useBatchDoc, useBatchDoc$, useBatchQuery, useBatchQuery$, useBatchQueryIds, useBatchQueryDoc, useBatchQueryDoc$ } from './orm/Compat/hooksCompat.js';
 export { emit, useOn, useEmit } from './orm/Compat/eventsCompat.js';
 export { useDidUpdate, useOnce, useSyncEffect } from "./react/helpers.js";
 export { connection, setConnection, getConnection, getDefaultFetchOnly, setDefaultFetchOnly, publicOnly, setPublicOnly } from "./orm/connection.js";

package/dist/orm/Compat/SignalCompat.js

@@ -21,7 +21,7 @@ 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'];
-    static [GETTERS] = [...DEFAULT_GETTERS, 'getCopy', 'getDeepCopy'];
+    static [GETTERS] = DEFAULT_GETTERS;
     path() {
         if (arguments.length > 0)
             throw Error('Signal.path() does not accept any arguments');

package/dist/orm/Compat/queryReadiness.d.ts

@@ -1,5 +1,13 @@
-export function isQueryReady(collection: any, idsSegments: any, docsSegments: any, extraSegments: any, aggregationSegments: any, isAggregate: any, hasExtraResult: any): boolean;
-export function isDocReady(segments: any): boolean;
-export function waitForImperativeQueryReady($query: any): Promise<void>;
-export function __setImperativeQueryReadyTimeoutForTests(timeoutMs: any): void;
-export function __resetImperativeQueryReadyTimeoutForTests(): void;
+import type { PathSegment } from '../types/path.js'
+
+export function isDocReady (segments: readonly PathSegment[]): boolean
+
+export function isQueryReady (
+  collection: string,
+  idsSegments: readonly PathSegment[],
+  docsSegments: readonly PathSegment[],
+  extraSegments: readonly PathSegment[],
+  aggregationSegments: readonly PathSegment[],
+  isAggregate: boolean,
+  hasExtraResult: boolean
+): boolean

package/dist/orm/Query.d.ts

@@ -113,5 +113,6 @@ export class QuerySubscriptions {
 
 export const querySubscriptions: QuerySubscriptions
 export function getQuerySignal (collectionName: string, params: unknown, options?: QuerySignalOptions): Signal
+export function materializeQueryDataDocsToCollection (collectionName: string, docs: unknown): void
 export function hashQuery (collectionName: string, params: unknown): string
 export function parseQueryHash (hash: string): QueryHashParts

package/dist/orm/Query.js

@@ -901,6 +901,24 @@ function maybeMaterializeQueryDocsToCollection(collectionName, shareDocs) {
         _set([collectionName, doc.id], raw(doc.data));
     }
 }
+export function materializeQueryDataDocsToCollection(collectionName, docs) {
+    if (!Array.isArray(docs))
+        return;
+    for (const doc of docs) {
+        const rawDoc = raw(doc);
+        if (!isPlainObject(rawDoc))
+            continue;
+        const docId = rawDoc._id ?? rawDoc.id;
+        if (docId == null)
+            continue;
+        const existing = getRaw([collectionName, docId]);
+        if (existing != null)
+            continue;
+        const idFields = getIdFieldsForSegments([collectionName, docId]);
+        injectIdFields(rawDoc, idFields, docId);
+        _set([collectionName, docId], rawDoc);
+    }
+}
 export function hashQuery(collectionName, params) {
     params = normalizeQueryParamsForHash(params);
     // TODO: probably makes sense to use fast-stable-json-stringify for this because of the params

package/dist/orm/SignalBase.d.ts

@@ -54,6 +54,12 @@ export declare class Signal<TValue = unknown> extends Function {
     get(): TValue;
     /** Return document ids for a query or aggregation signal. */
     getIds(): string[];
+    /** Return query extra data, aggregation data, or undefined for ordinary signals. */
+    getExtra(): unknown;
+    /** Return a shallow copy of the current value. */
+    getCopy(): TValue;
+    /** Return a deep copy of the current value. */
+    getDeepCopy(): TValue;
     /** Read the current value without tracking it for reactive rendering. */
     peek(): TValue;
     /** Return the document id represented by this document signal. */
@@ -105,6 +111,18 @@ export declare class Signal<TValue = unknown> extends Function {
      * @param value New value to store at this signal path.
      */
     setReplace(value: TValue): Promise<void>;
+    /** Set the current value only when it is null or undefined. */
+    setNull(value: TValue): Promise<void>;
+    /** Replace the current value unless it is exactly equal to the new value. */
+    setDiff(value: TValue): Promise<void>;
+    /** Recursively diff objects and arrays at the current signal path. */
+    setDiffDeep(value: TValue): Promise<void>;
+    /**
+     * Set multiple object fields with per-key replace semantics.
+     * Unlike assign(), null is stored as null and undefined follows setReplace() semantics.
+     * @param object Object containing fields to set.
+     */
+    setEach(object: NonNullable<TValue> extends object ? Partial<NonNullable<TValue>> : never): Promise<void>;
     /**
      * Set multiple object fields at once. Fields set to `null` or `undefined` are deleted.
      * @param value Object containing fields to set or delete.

package/dist/orm/SignalBase.js

@@ -12,15 +12,17 @@
  * 3. If extremely late bindings are enabled, to prevent name collisions when accessing fields
  *    in the raw data tree which have the same name as signal's methods
  */
+import { raw } from '@nx-js/observer-util';
+import arrayDiff from 'arraydiff';
 import uuid from '@teamplay/utils/uuid';
 import { get as _get, setPublicDoc as _setPublicDoc, setPublicDocReplace as _setPublicDocReplace, del as _del, dataTreeRaw, getRaw, getLogicalRootSnapshot, incrementPublic as _incrementPublic, arrayPushPublic as _arrayPushPublic, arrayUnshiftPublic as _arrayUnshiftPublic, arrayInsertPublic as _arrayInsertPublic, arrayPopPublic as _arrayPopPublic, arrayShiftPublic as _arrayShiftPublic, arrayRemovePublic as _arrayRemovePublic, arrayMovePublic as _arrayMovePublic, stringInsertPublic as _stringInsertPublic, stringRemovePublic as _stringRemovePublic } from './dataTree.js';
 import getSignal, { rawSignal } from "./getSignal.js";
 import { docSubscriptions } from './Doc.js';
 import { IS_QUERY, HASH, QUERIES } from './Query.js';
-import { AGGREGATIONS, getAggregationCollectionName, getAggregationDocId } from './Aggregation.js';
+import { AGGREGATIONS, IS_AGGREGATION, getAggregationCollectionName, getAggregationDocId } from './Aggregation.js';
 import { ROOT_FUNCTION, ROOT_ID, getRoot } from "./Root.js";
 import { isPrivateMutationForbidden } from "./connection.js";
-import { DEFAULT_ID_FIELDS, getIdFieldsForSegments, isIdFieldPath, isPublicDocPath, normalizeIdFields, prepareAddPayload, resolveAddDocId } from "./idFields.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';
 import { compatStartOnRoot, compatStopOnRoot, joinScopePath } from './Compat/startStopCompat.js';
@@ -202,6 +204,28 @@ export class Signal extends Function {
             throw Error('Signal.getIds() does not accept any arguments');
         return getSignalIds(this, SIGNAL_READ_CONTEXT);
     }
+    /** Return query extra data, aggregation data, or undefined for ordinary signals. */
+    getExtra() {
+        if (arguments.length > 0)
+            throw Error('Signal.getExtra() does not accept any arguments');
+        if (this[IS_AGGREGATION])
+            return this.get();
+        if (this[IS_QUERY])
+            return this.extra.get();
+        return undefined;
+    }
+    /** Return a shallow copy of the current value. */
+    getCopy() {
+        if (arguments.length > 0)
+            throw Error('Signal.getCopy() does not accept any arguments');
+        return shallowCopy(this.get());
+    }
+    /** Return a deep copy of the current value. */
+    getDeepCopy() {
+        if (arguments.length > 0)
+            throw Error('Signal.getDeepCopy() does not accept any arguments');
+        return deepCopy(this.get());
+    }
     /** Read the current value without tracking it for reactive rendering. */
     peek() {
         if (arguments.length > 0)
@@ -292,6 +316,50 @@ export class Signal extends Function {
         }
         setReplacePrivateData(getSignalOwningRootId(this), segments, nextValue);
     }
+    /** Set the current value only when it is null or undefined. */
+    async setNull(value) {
+        if (arguments.length > 1)
+            throw Error('Signal.setNull() expects a single argument');
+        if (this.get() != null)
+            return;
+        await this.setReplace(value);
+    }
+    /** Replace the current value unless it is exactly equal to the new value. */
+    async setDiff(value) {
+        if (arguments.length > 1)
+            throw Error('Signal.setDiff() expects a single argument');
+        const before = this.peek();
+        if (racerEqual(before, value))
+            return;
+        await this.setReplace(value);
+    }
+    /** Recursively diff objects and arrays at the current signal path. */
+    async setDiffDeep(value) {
+        if (arguments.length > 1)
+            throw Error('Signal.setDiffDeep() expects a single argument');
+        await runInBatch(() => setDiffDeepOnSignal(this, value));
+    }
+    /**
+     * Set multiple object fields with per-key replace semantics.
+     * Unlike assign(), null is stored as null and undefined follows setReplace() semantics.
+     * @param object Object containing fields to set.
+     */
+    async setEach(object) {
+        if (arguments.length > 1)
+            throw Error('Signal.setEach() expects a single argument');
+        if (!object)
+            return;
+        if (typeof object !== 'object') {
+            throw Error('Signal.setEach() expects an object argument, got: ' + typeof object);
+        }
+        await runInBatch(async () => {
+            const promises = [];
+            for (const key of Object.keys(object)) {
+                promises.push(this[key].setReplace(object[key]));
+            }
+            await Promise.all(promises);
+        });
+    }
     /**
      * Set multiple object fields at once. Fields set to `null` or `undefined` are deleted.
      * @param value Object containing fields to set or delete.
@@ -522,6 +590,183 @@ export class Signal extends Function {
         await deleteSignalValue(this, SIGNAL_VALUE_MUTATION_CONTEXT);
     }
 }
+async function setDiffDeepOnSignal($target, value) {
+    if ($target[SEGMENTS].length === 0)
+        throw Error('Can\'t set the root signal data');
+    await diffDeepOnSignal($target, $target.peek(), value);
+}
+async function diffDeepOnSignal($signal, before, after) {
+    if (before === after)
+        return;
+    if (Array.isArray(before) && Array.isArray(after)) {
+        const diff = arrayDiff(before, after, deepEqual);
+        if (!diff.length)
+            return;
+        const index = getSingleArrayReplacementIndex(diff);
+        if (index != null) {
+            await diffDeepOnSignal(getChildSignal($signal, index), before[index], after[index]);
+            return;
+        }
+        await applyArrayDiff($signal, diff);
+        return;
+    }
+    if (isDiffableObject(before, after)) {
+        const preservePath = $signal[SEGMENTS];
+        for (const key of Object.keys(before)) {
+            if (Object.prototype.hasOwnProperty.call(after, key))
+                continue;
+            await deleteForDiffDeep(getChildSignal($signal, key), preservePath);
+        }
+        for (const key of Object.keys(after)) {
+            await diffDeepOnSignal(getChildSignal($signal, key), before[key], after[key]);
+        }
+        return;
+    }
+    await $signal.setReplace(after);
+}
+function isDiffableObject(before, after) {
+    if (!isPlainObject(before) || !isPlainObject(after))
+        return false;
+    if (isReactLike(before) || isReactLike(after))
+        return false;
+    return true;
+}
+function isReactLike(value) {
+    return !!(value && typeof value === 'object' && typeof value.$$typeof === 'symbol');
+}
+function getSingleArrayReplacementIndex(diff) {
+    if (!Array.isArray(diff) || diff.length !== 2)
+        return null;
+    const first = diff[0];
+    const second = diff[1];
+    if (first instanceof arrayDiff.RemoveDiff &&
+        second instanceof arrayDiff.InsertDiff &&
+        first.index === second.index &&
+        first.howMany === 1 &&
+        second.values.length === 1) {
+        return first.index;
+    }
+    return null;
+}
+async function applyArrayDiff($signal, diff) {
+    for (const item of diff) {
+        if (item instanceof arrayDiff.InsertDiff) {
+            await $signal.insert(item.index, item.values);
+            continue;
+        }
+        if (item instanceof arrayDiff.RemoveDiff) {
+            await $signal.remove(item.index, item.howMany);
+            continue;
+        }
+        if (item instanceof arrayDiff.MoveDiff) {
+            await $signal.move(item.from, item.to, item.howMany);
+        }
+    }
+}
+async function deleteForDiffDeep($signal, preservePath) {
+    const segments = $signal[SEGMENTS];
+    const idFields = getIdFieldsForSegments(segments);
+    if (isIdFieldPath(segments, idFields))
+        return;
+    if (isPublicCollection(segments[0])) {
+        await $signal.del();
+        return;
+    }
+    if (isPrivateMutationForbidden()) {
+        throw Error(`
+      Can't modify private collections data when 'publicOnly' is enabled.
+      On the server you can only work with public collections.
+    `);
+    }
+    delPrivateData(getSignalOwningRootId($signal), segments, { preservePath });
+}
+function getChildSignal($parent, key) {
+    return getSignal(getRoot($parent) || $parent, [...$parent[SEGMENTS], key]);
+}
+function deepEqual(left, right) {
+    if (left === right)
+        return true;
+    if (left == null || right == null)
+        return false;
+    if (typeof left !== 'object' || typeof right !== 'object')
+        return false;
+    if (Array.isArray(left) !== Array.isArray(right))
+        return false;
+    if (Array.isArray(left)) {
+        if (left.length !== right.length)
+            return false;
+        for (let i = 0; i < left.length; i++) {
+            if (!deepEqual(left[i], right[i]))
+                return false;
+        }
+        return true;
+    }
+    if (!isPlainObject(left) || !isPlainObject(right))
+        return false;
+    const leftKeys = Object.keys(left);
+    const rightKeys = Object.keys(right);
+    if (leftKeys.length !== rightKeys.length)
+        return false;
+    for (const key of leftKeys) {
+        if (!Object.prototype.hasOwnProperty.call(right, key))
+            return false;
+        if (!deepEqual(left[key], right[key]))
+            return false;
+    }
+    return true;
+}
+function racerEqual(left, right) {
+    return left === right || (Number.isNaN(left) && Number.isNaN(right));
+}
+function shallowCopy(value) {
+    const rawValue = raw(value);
+    if (Array.isArray(rawValue))
+        return rawValue.slice();
+    if (rawValue && typeof rawValue === 'object')
+        return { ...rawValue };
+    return rawValue;
+}
+function deepCopy(value) {
+    const rawValue = raw(value);
+    if (!rawValue || typeof rawValue !== 'object')
+        return rawValue;
+    if (typeof globalThis.structuredClone === 'function') {
+        try {
+            return globalThis.structuredClone(rawValue);
+        }
+        catch { }
+    }
+    return racerDeepCopy(rawValue);
+}
+// Racer-style deep copy:
+// - Preserves prototypes by instantiating via `new value.constructor()`
+// - Copies own enumerable props recursively
+// - Keeps functions as-is (no cloning)
+// - Handles Date by creating a new Date
+// Limitations: does not handle cyclic refs, Map/Set/RegExp/TypedArray, non-enumerables.
+function racerDeepCopy(value) {
+    if (value instanceof Date)
+        return new Date(value);
+    if (typeof value === 'object') {
+        if (value === null)
+            return null;
+        if (Array.isArray(value)) {
+            const array = [];
+            for (let i = value.length; i--;) {
+                array[i] = racerDeepCopy(value[i]);
+            }
+            return array;
+        }
+        const object = new value.constructor();
+        for (const key in value) {
+            if (Object.prototype.hasOwnProperty.call(value, key)) {
+                object[key] = racerDeepCopy(value[key]);
+            }
+        }
+        return object;
+    }
+    return value;
+}
 // dot syntax returns a child signal only if no such method or property exists
 export const regularBindings = {
     apply(signal, thisArg, argumentsList) {

package/dist/orm/privateData.d.ts

@@ -1,22 +1,7 @@
-export function getPrivateDataRoot(rootId: any, create?: boolean): {
-    [x: string]: unknown;
-    [x: number]: unknown;
-};
-export function getPrivateDataRawRoot(rootId: any, create?: boolean): {
-    [x: string]: unknown;
-    [x: number]: unknown;
-};
-export function getPrivateData(rootId: any, logicalSegments: any, raw?: boolean): unknown;
-export function setPrivateData(rootId: any, logicalSegments: any, value: any): void;
-export function setReplacePrivateData(rootId: any, logicalSegments: any, value: any): void;
-export function delPrivateData(rootId: any, logicalSegments: any, options?: {}): void;
-export function arrayPushPrivateData(rootId: any, logicalSegments: any, value: any): number | undefined;
-export function arrayUnshiftPrivateData(rootId: any, logicalSegments: any, value: any): number | undefined;
-export function arrayInsertPrivateData(rootId: any, logicalSegments: any, index: any, values: any): number | undefined;
-export function arrayPopPrivateData(rootId: any, logicalSegments: any): any;
-export function arrayShiftPrivateData(rootId: any, logicalSegments: any): any;
-export function arrayRemovePrivateData(rootId: any, logicalSegments: any, index: any, howMany?: number): any[] | undefined;
-export function arrayMovePrivateData(rootId: any, logicalSegments: any, from: any, to: any, howMany?: number): any[] | undefined;
-export function stringInsertPrivateData(rootId: any, logicalSegments: any, index: any, text: any): any;
-export function stringRemovePrivateData(rootId: any, logicalSegments: any, index: any, howMany: any): any;
-export function getPrivateDataSnapshot(rootId: any): any;
+import type { PathSegment } from './types/path.js'
+
+export function getPrivateData (
+  rootId: string | undefined,
+  logicalSegments: readonly PathSegment[],
+  raw?: boolean
+): unknown

package/dist/orm/signalSymbols.js

@@ -2,4 +2,4 @@ export const SEGMENTS = Symbol('path segments targeting the particular node in t
 export const ARRAY_METHOD = Symbol('run array method on the signal');
 export const GET = Symbol('get the value of the signal - either observed or raw');
 export const GETTERS = Symbol('get the list of this signal\'s getters');
-export const DEFAULT_GETTERS = ['path', 'root', 'id', 'get', 'peek', 'getId', 'map', 'reduce', 'find', 'getIds', 'getExtra', 'getCollection'];
+export const DEFAULT_GETTERS = ['path', 'root', 'id', 'get', 'peek', 'getId', 'map', 'reduce', 'find', 'getIds', 'getExtra', 'getCopy', 'getDeepCopy', 'getCollection'];

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/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;
         }

package/dist/react/useSub.d.ts

@@ -66,6 +66,75 @@ 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.

package/dist/react/useSub.js

@@ -3,6 +3,12 @@ import sub from "../orm/sub.js";
 import { useScheduleUpdate, useCache, useDefer } from "./helpers.js";
 import executionContextTracker from "./executionContextTracker.js";
 import * as promiseBatcher from "./promiseBatcher.js";
+import { getPrivateData } from '../orm/privateData.js';
+import { isDocReady } from '../orm/Compat/queryReadiness.js';
+import { getRoot, ROOT_ID } from "../orm/Root.js";
+import { COLLECTION_NAME, HASH, IS_QUERY, PARAMS, QUERIES, querySubscriptions, materializeQueryDataDocsToCollection } from '../orm/Query.js';
+import { AGGREGATIONS, IS_AGGREGATION, aggregationSubscriptions } from '../orm/Aggregation.js';
+import { SEGMENTS } from "../orm/signalSymbols.js";
 import { isPublicDocumentSignal } from "../orm/Signal.js";
 const runtimeSub = sub;
 const USE_SUB_OPTION_KEYS = new Set(['async', 'defer', 'batch']);
@@ -16,6 +22,14 @@ export function useAsyncSub(signal, params, options) {
     const normalized = normalizeUseSubArgs(signal, params, options);
     return runUseSub(normalized.signal, normalized.params, { ...normalized.options, async: true });
 }
+export function useBatchSub(signal, params, options) {
+    const callUseSub = useSub;
+    if (arguments.length === 0) {
+        return callUseSub(undefined, undefined, { batch: true });
+    }
+    const normalized = normalizeUseSubArgs(signal, params, options);
+    return callUseSub(normalized.signal, normalized.params, { ...normalized.options, async: false, batch: true });
+}
 export default function useSub(signal, params, options) {
     const normalized = normalizeUseSubArgs(signal, params, options);
     return runUseSub(normalized.signal, normalized.params, normalized.options);
@@ -36,6 +50,8 @@ function isUseSubOptions(value) {
     return Object.keys(value).every(key => USE_SUB_OPTION_KEYS.has(key));
 }
 function runUseSub(signal, params, options) {
+    if (isBatchBarrierCall(signal, params, options))
+        return closeBatchBarrier();
     if (USE_DEFERRED_VALUE) {
         return useSubDeferred(signal, params, options); // eslint-disable-line react-hooks/rules-of-hooks
     }
@@ -43,6 +59,14 @@ function runUseSub(signal, params, options) {
         return useSubClassic(signal, params, options); // eslint-disable-line react-hooks/rules-of-hooks
     }
 }
+function isBatchBarrierCall(signal, params, options) {
+    return signal === undefined && params === undefined && !!options?.batch;
+}
+function closeBatchBarrier() {
+    const promise = promiseBatcher.getPromiseAll();
+    if (promise)
+        throw promise;
+}
 // version of sub() which works as a react hook and throws promise for Suspense
 export function useSubDeferred(signal, params, { async = false, defer, batch = false } = {}) {
     const $signalRef = useRef();
@@ -60,18 +84,20 @@ export function useSubDeferred(signal, params, { async = false, defer, batch = f
     // 1. if it's a promise, throw it so that Suspense can catch it and wait for subscription to finish
     if (isThenable(promiseOrSignal)) {
         const promise = maybeThrottle(promiseOrSignal);
+        const readyPromise = batch ? getBatchReadyPromise(promise) : promise;
         const hasPreviousSignal = !!$signalRef.current;
         if (batch) {
             // Batch suspense must block only on initial load.
             // On resubscribe we keep rendering previous signal and refresh in background.
             if (!hasPreviousSignal) {
                 promiseBatcher.add(promise);
+                addBatchReadinessCheck(promise);
             }
             else {
-                scheduleUpdate(promise);
+                scheduleUpdate(readyPromise);
             }
             if (async)
-                scheduleUpdate(promise);
+                scheduleUpdate(readyPromise);
             return $signalRef.current;
         }
         if (async) {
@@ -88,6 +114,8 @@ export function useSubDeferred(signal, params, { async = false, defer, batch = f
     }
     else {
         const $signal = promiseOrSignal;
+        if (batch && !$signalRef.current)
+            addBatchReadinessCheckForSignal($signal);
         if ($signalRef.current !== $signal)
             $signalRef.current = $signal;
         return $signal;
@@ -105,18 +133,20 @@ export function useSubClassic(signal, params, { async = false, batch = false } =
     // 1. if it's a promise, throw it so that Suspense can catch it and wait for subscription to finish
     if (isThenable(promiseOrSignal)) {
         const promise = maybeThrottle(promiseOrSignal);
+        const readyPromise = batch ? getBatchReadyPromise(promise) : promise;
         if (batch) {
             const hasPreviousSignal = cache.has(id);
             // Batch suspense must block only on initial load.
             // On resubscribe we keep rendering previous signal and refresh in background.
             if (!hasPreviousSignal) {
                 promiseBatcher.add(promise);
+                addBatchReadinessCheck(promise);
             }
             else {
-                scheduleUpdate(promise);
+                scheduleUpdate(readyPromise);
             }
             if (async)
-                scheduleUpdate(promise);
+                scheduleUpdate(readyPromise);
             if (hasPreviousSignal)
                 return cache.get(id);
             return;
@@ -143,6 +173,8 @@ export function useSubClassic(signal, params, { async = false, batch = false } =
     }
     else {
         const $signal = promiseOrSignal;
+        if (batch && !cache.has(id))
+            addBatchReadinessCheckForSignal($signal);
         if (cache.get(id) !== $signal) {
             cache.set(id, $signal);
         }
@@ -178,6 +210,137 @@ function maybeThrottle(promise) {
         }, delay);
     });
 }
+function addBatchReadinessCheck(promise) {
+    let resolvedSignal;
+    let resolved = false;
+    promise.then(signal => {
+        resolvedSignal = signal;
+        resolved = true;
+    }, () => {
+        resolved = true;
+    });
+    promiseBatcher.addCheck({
+        key: promise,
+        type: 'subscription',
+        isReady: () => resolved && isBatchSignalReady(resolvedSignal),
+        getState: () => getBatchSignalState(resolvedSignal)
+    });
+}
+function getBatchReadyPromise(promise) {
+    return Promise.resolve(promise).then(async (signal) => {
+        await waitForBatchSignalReady(signal);
+        return signal;
+    });
+}
+async function waitForBatchSignalReady(signal) {
+    while (!isBatchSignalReady(signal)) {
+        await new Promise(resolve => setTimeout(resolve, 16));
+    }
+}
+function addBatchReadinessCheckForSignal(signal) {
+    if (isBatchSignalReady(signal))
+        return;
+    const promise = Promise.resolve(signal);
+    promiseBatcher.add(promise);
+    addBatchReadinessCheck(promise);
+}
+function isBatchSignalReady(signal) {
+    if (isPublicDocumentSignal(signal)) {
+        const $doc = signal;
+        return isDocReady($doc[SEGMENTS]);
+    }
+    if (isQuerySignal(signal))
+        return isBatchQueryReady(signal);
+    return true;
+}
+function isBatchQueryReady(signal) {
+    const collection = signal[COLLECTION_NAME];
+    const params = signal[PARAMS];
+    if (!isBatchQueryTransportStable(signal))
+        return false;
+    const hasExtraResult = isExtraQuery(params);
+    if (hasExtraResult)
+        return readQueryExtra(signal) !== undefined;
+    const isAggregate = !!signal[IS_AGGREGATION] || isAggregationQuery(params);
+    const docs = signal.get();
+    if (isAggregate) {
+        if (Array.isArray(docs))
+            return true;
+        return readQueryExtra(signal) !== undefined;
+    }
+    if (!Array.isArray(docs))
+        return false;
+    materializeQueryDataDocsToCollection(collection, docs);
+    const ids = signal.getIds();
+    for (const id of ids) {
+        if (id == null)
+            continue;
+        if (!isDocReady([collection, id]))
+            return false;
+    }
+    return true;
+}
+function isBatchQueryTransportStable(signal) {
+    const subscriptions = signal[IS_AGGREGATION] ? aggregationSubscriptions : querySubscriptions;
+    const entry = subscriptions.entries.get(signal[HASH]);
+    if (!entry)
+        return false;
+    return entry.phase === 'stable' && entry.mode === entry.targetMode;
+}
+function getBatchSignalState(signal) {
+    if (isPublicDocumentSignal(signal)) {
+        const $doc = signal;
+        return {
+            kind: 'doc',
+            path: $doc[SEGMENTS],
+            ready: isDocReady($doc[SEGMENTS])
+        };
+    }
+    if (!isQuerySignal(signal))
+        return { kind: 'unknown', resolved: !!signal };
+    const rootId = getRoot(signal)?.[ROOT_ID];
+    const hash = signal[HASH];
+    const collection = signal[COLLECTION_NAME];
+    return {
+        kind: signal[IS_AGGREGATION] ? 'aggregation' : 'query',
+        collection,
+        hash,
+        ids: getPrivateData(rootId, [QUERIES, hash, 'ids'], true),
+        hasDocs: Array.isArray(getPrivateData(rootId, [QUERIES, hash, 'docs'], true)),
+        hasExtra: getPrivateData(rootId, [QUERIES, hash, 'extra'], true) !== undefined,
+        hasAggregation: getPrivateData(rootId, [AGGREGATIONS, hash], true) !== undefined
+    };
+}
+function readQueryExtra(signal) {
+    try {
+        return signal.extra.get();
+    }
+    catch (err) {
+        if (isThenable(err))
+            return undefined;
+        throw err;
+    }
+}
+function isQuerySignal(signal) {
+    return !!signal &&
+        (typeof signal === 'object' || typeof signal === 'function') &&
+        !!signal[IS_QUERY] &&
+        typeof signal[COLLECTION_NAME] === 'string' &&
+        typeof signal[HASH] === 'string';
+}
+function isExtraQuery(query) {
+    if (!query || typeof query !== 'object')
+        return false;
+    return !!(query.$count ||
+        query.$queryName ||
+        query.$aggregationName);
+}
+function isAggregationQuery(query) {
+    if (!query || typeof query !== 'object')
+        return false;
+    return !!(query.$aggregate ||
+        query.$aggregationName);
+}
 function isThenable(value) {
     return !!value &&
         (typeof value === 'object' || typeof value === 'function') &&

package/package.json

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

package/dist/orm/Compat/hooksCompat.d.ts

@@ -1,8 +0,0 @@
-export const useBatch: any
-export const useBatchDoc: any
-export const useBatchDoc$: any
-export const useBatchQuery: any
-export const useBatchQuery$: any
-export const useBatchQueryIds: any
-export const useBatchQueryDoc: any
-export const useBatchQueryDoc$: any

package/dist/orm/Compat/hooksCompat.js

@@ -1,151 +0,0 @@
-import { getRootSignal, GLOBAL_ROOT_ID } from "../Root.js";
-import useSub from "../../react/useSub.js";
-import universal$ from "../../react/universal$.js";
-import * as promiseBatcher from "../../react/promiseBatcher.js";
-import { isQueryReady } from './queryReadiness.js';
-const $root = getRootSignal({ rootId: GLOBAL_ROOT_ID, rootFunction: universal$ });
-const emittedCompatWarnings = new Set();
-export function useBatch() {
-    const promise = promiseBatcher.getPromiseAll();
-    if (promise)
-        throw promise;
-}
-export function useBatchDoc(collection, id, options) {
-    const $doc = useBatchDoc$(collection, id, options);
-    if (!$doc)
-        return [undefined, undefined];
-    return [$doc.get(), $doc];
-}
-export function useBatchDoc$(collection, id, _options) {
-    const $doc = getDocSignal(collection, id, 'useBatchDoc');
-    const options = _options ? { ..._options, ...BATCH_SUB_OPTIONS } : BATCH_SUB_OPTIONS;
-    return useSub($doc, undefined, options);
-}
-function useSubscribedQuery(collection, query, options, hookName, subscribe) {
-    const normalizedQuery = normalizeQuery(query, hookName);
-    const $collection = getCollectionSignal(collection, query, hookName);
-    const $query = subscribe($collection, normalizedQuery, options);
-    return {
-        normalizedQuery,
-        $collection,
-        $query: getExtraQuerySignal($query, normalizedQuery)
-    };
-}
-function getExtraQuerySignal($query, normalizedQuery) {
-    if (!$query)
-        return $query;
-    return isExtraQuery(normalizedQuery) ? $query.extra : $query;
-}
-export function useBatchQuery$(collection, query, _options) {
-    const options = normalizeBatchSubOptions(_options);
-    const { $query } = useSubscribedQuery(collection, query, options, 'useBatchQuery', useSub);
-    return $query;
-}
-export function useBatchQuery(collection, query, _options) {
-    const options = normalizeBatchSubOptions(_options);
-    const { $collection, $query } = useSubscribedQuery(collection, query, options, 'useBatchQuery', useSub);
-    if (!$query)
-        return [undefined, $collection];
-    return [$query.get(), $collection];
-}
-export function useBatchQueryIds(collection, ids = [], options = {}) {
-    const list = Array.isArray(ids) ? ids.slice() : [];
-    if (options?.reverse)
-        list.reverse();
-    const [docs, $collection] = useBatchQuery(collection, { _id: { $in: list } }, options);
-    if (!docs)
-        return [docs, $collection];
-    const docsById = new Map();
-    for (const doc of docs) {
-        const id = doc?._id ?? doc?.id;
-        if (id != null)
-            docsById.set(id, doc);
-    }
-    const items = list.map(id => docsById.get(id)).filter(Boolean);
-    return [items, $collection];
-}
-export function useBatchQueryDoc(collection, query, options) {
-    const normalized = normalizeQuery(query, 'useBatchQueryDoc');
-    const queryDoc = {
-        ...normalized,
-        $limit: 1,
-        $sort: normalized.$sort || { createdAt: -1 }
-    };
-    const [docs, $collection] = useBatchQuery(collection, queryDoc, options);
-    if (!docs)
-        return [undefined, undefined];
-    const doc = docs && docs[0];
-    const docId = doc?._id ?? doc?.id;
-    const $doc = docId != null ? $collection[docId] : undefined;
-    return [doc, $doc];
-}
-export function useBatchQueryDoc$(collection, query, options) {
-    const [, $doc] = useBatchQueryDoc(collection, query, options);
-    return $doc;
-}
-function getDocSignal(collection, id, hookName) {
-    if (typeof collection !== 'string') {
-        throw Error(`[${hookName}] collection must be a string. Got: ${collection}`);
-    }
-    if (id == null) {
-        warnCompatOnce(`doc:${hookName}:${collection}:${id}`, `
-      [${hookName}] You are trying to subscribe to an undefined document id:
-        ${collection}.${id}
-      Falling back to '__NULL__' document to prevent critical crash.
-      You should prevent situations when the \`id\` is undefined.
-    `);
-        id = '__NULL__';
-    }
-    return $root[collection][id];
-}
-function getCollectionSignal(collection, query, hookName) {
-    if (typeof collection !== 'string') {
-        throw Error(`[${hookName}] collection must be a string. Got: ${collection}`);
-    }
-    if (query == null) {
-        warnCompatOnce(`query:${hookName}:${collection}`, `
-      [${hookName}] Query is undefined. Got:
-        ${collection}, ${query}
-      Falling back to {_id: '__NON_EXISTENT__'} query to prevent critical crash.
-      You should prevent situations when the \`query\` is undefined.
-    `);
-    }
-    return $root[collection];
-}
-function warnCompatOnce(key, message) {
-    if (emittedCompatWarnings.has(key))
-        return;
-    emittedCompatWarnings.add(key);
-    console.warn(message);
-}
-export function __resetCompatWarningsForTests() {
-    emittedCompatWarnings.clear();
-}
-function normalizeQuery(query, hookName) {
-    if (query == null)
-        return { _id: '__NON_EXISTENT__' };
-    if (typeof query !== 'object') {
-        throw Error(`[${hookName}] query must be an object. Got: ${query}`);
-    }
-    return query;
-}
-function isExtraQuery(query) {
-    if (!query || typeof query !== 'object')
-        return false;
-    return !!(query.$count ||
-        query.$queryName ||
-        query.$aggregationName);
-}
-const BATCH_SUB_OPTIONS = Object.freeze({
-    async: false,
-    batch: true,
-    // Batch hooks are a hard suspense barrier. Deferred params can skip the barrier
-    // on route transitions and cause immediate reads from stale/empty local nodes.
-    defer: false
-});
-function normalizeBatchSubOptions(options) {
-    return options ? { ...options, ...BATCH_SUB_OPTIONS } : BATCH_SUB_OPTIONS;
-}
-export const __COMPAT_BATCH_READY__ = {
-    isQueryReady
-};