teamplay 0.5.0-alpha.8 → 0.5.0

package/dist/orm/idFields.js

@@ -1,8 +1,42 @@
 import { findModel } from "./addModel.js";
 export const DEFAULT_ID_FIELDS = ['_id'];
+export const TEAMPLAY_RUNTIME_CONFIG_SYMBOL = Symbol.for('teamplay.runtimeConfig');
 export function getIdFieldsForSegments(segments) {
     const Model = findModel(segments);
-    return Model?.ID_FIELDS || DEFAULT_ID_FIELDS;
+    return Model?.ID_FIELDS || getDefaultIdFields();
+}
+export function configureTeamplay({ idFields } = {}) {
+    if (arguments.length === 0)
+        return;
+    const config = getGlobalRuntimeConfig(true);
+    const options = (arguments[0] || {});
+    if (Object.prototype.hasOwnProperty.call(options, 'idFields')) {
+        config.idFields = idFields == null
+            ? DEFAULT_ID_FIELDS
+            : normalizeIdFieldsConfig(idFields);
+    }
+}
+export function getTeamplayConfig() {
+    return {
+        idFields: getDefaultIdFields()
+    };
+}
+export function getDefaultIdFields() {
+    const config = getGlobalRuntimeConfig(false);
+    if (!config || !Object.prototype.hasOwnProperty.call(config, 'idFields')) {
+        return DEFAULT_ID_FIELDS;
+    }
+    if (config.idFields == null)
+        return DEFAULT_ID_FIELDS;
+    const normalized = normalizeIdFieldsConfig(config.idFields);
+    config.idFields = normalized;
+    return normalized;
+}
+export function setDefaultIdFields(idFields = DEFAULT_ID_FIELDS) {
+    getGlobalRuntimeConfig(true).idFields = normalizeIdFieldsConfig(idFields);
+}
+export function __resetTeamplayConfigForTests() {
+    delete getGlobalRuntimeConfigHolder()[TEAMPLAY_RUNTIME_CONFIG_SYMBOL];
 }
 export function isPlainObject(value) {
     if (!value || typeof value !== 'object')
@@ -52,26 +86,28 @@ export function stripIdFields(value, idFields) {
     }
     return next;
 }
-export function resolveAddDocId(value, getDefaultId) {
+export function resolveAddDocId(value, idFields, getDefaultId) {
     if (!value || typeof value !== 'object')
         throw Error('Signal.add() expects an object argument');
     const payload = value;
-    const hasId = payload.id != null;
-    const hasUnderscoreId = payload._id != null;
-    if (hasId && hasUnderscoreId && payload.id !== payload._id) {
-        throw Error(`Signal.add() got conflicting "id" (${JSON.stringify(payload.id)}) and "_id" (${JSON.stringify(payload._id)})`);
+    const entries = getAddIdEntries(payload, idFields);
+    const [firstEntry] = entries;
+    const conflictEntry = firstEntry && entries.find(entry => entry.value !== firstEntry.value);
+    if (firstEntry && conflictEntry) {
+        throw Error(`Signal.add() got conflicting "${firstEntry.field}" (${JSON.stringify(firstEntry.value)}) ` +
+            `and "${conflictEntry.field}" (${JSON.stringify(conflictEntry.value)}) id fields`);
     }
-    return payload.id ?? payload._id ?? getDefaultId();
+    return firstEntry?.value ?? getDefaultId();
 }
 export function prepareAddPayload(value, idFields, docId) {
     const payload = value;
-    if (idFields.includes('_id'))
-        payload._id = docId;
-    if (idFields.includes('id')) {
-        payload.id = docId;
-    }
-    else if (payload.id === docId) {
-        delete payload.id;
+    for (const field of idFields)
+        payload[field] = docId;
+    for (const field of LEGACY_ADD_ID_FIELDS) {
+        if (idFields.includes(field))
+            continue;
+        if (payload[field] === docId)
+            delete payload[field];
     }
     return value;
 }
@@ -93,3 +129,55 @@ export function isIdFieldPath(segments, idFields) {
     const last = segments[2];
     return typeof last === 'string' && idFields.includes(last);
 }
+function normalizeIdFieldsConfig(idFields) {
+    if (!Array.isArray(idFields)) {
+        throw Error('Teamplay idFields config must be an array of field names');
+    }
+    const normalized = [];
+    for (const field of idFields) {
+        if (typeof field !== 'string' || field.length === 0) {
+            throw Error('Teamplay idFields config must contain only non-empty string field names');
+        }
+        if (!normalized.includes(field))
+            normalized.push(field);
+    }
+    if (normalized.length === 0) {
+        throw Error('Teamplay idFields config must contain at least one field name');
+    }
+    return Object.freeze(normalized);
+}
+function getAddIdEntries(payload, idFields) {
+    const fields = uniqueFields([...LEGACY_ADD_ID_FIELDS, ...idFields]);
+    const entries = [];
+    for (const field of fields) {
+        const value = payload[field];
+        if (value == null)
+            continue;
+        entries.push({ field, value: value });
+    }
+    return entries;
+}
+function uniqueFields(fields) {
+    const result = [];
+    for (const field of fields) {
+        if (!result.includes(field))
+            result.push(field);
+    }
+    return result;
+}
+function getGlobalRuntimeConfig(create = true) {
+    const holder = getGlobalRuntimeConfigHolder();
+    let config = holder[TEAMPLAY_RUNTIME_CONFIG_SYMBOL];
+    if (config == null && create) {
+        config = {};
+        holder[TEAMPLAY_RUNTIME_CONFIG_SYMBOL] = config;
+    }
+    if (config != null && (!isPlainObject(config))) {
+        throw Error('Teamplay runtime config must be an object');
+    }
+    return config;
+}
+function getGlobalRuntimeConfigHolder() {
+    return globalThis;
+}
+const LEGACY_ADD_ID_FIELDS = ['id', '_id'];

package/dist/orm/index.d.ts

@@ -4,4 +4,6 @@ export type { RootSignal, TeamplayCollections, TeamplayFeature, TeamplayFeatures
 export declare const BaseModel: import("./Signal.js").SignalConstructor;
 export default BaseModel;
 export { defineModels, default as initModels, getModels, resetModelsForTests } from './initModels.js';
+export { default as reaction } from './reaction.js';
+export type { ReactionHandle, ReactionOptions } from './reaction.js';
 export { defineSchema } from '@teamplay/schema';

package/dist/orm/index.js

@@ -3,4 +3,5 @@ export { belongsTo, hasMany, hasOne } from "./associations.js";
 export const BaseModel = Signal;
 export default BaseModel;
 export { defineModels, default as initModels, getModels, resetModelsForTests } from "./initModels.js";
+export { default as reaction } from "./reaction.js";
 export { defineSchema } from '@teamplay/schema';

package/dist/orm/initModels.js

@@ -36,7 +36,7 @@ function warnIfSchemaWasNotDefined(pattern, schema) {
     warnedUnwrappedSchemaPatterns.add(pattern);
     console.warn(`[teamplay] Schema for model "${pattern}" was loaded as a plain object. ` +
         'Wrap it with defineSchema(schema) to enable the conventional schema setup. ' +
-        'Plain schemas still work for backward compatibility.');
+        'Plain schemas still work.');
 }
 function shouldWarnAboutUnwrappedSchemas() {
     const env = getProcessEnv();

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/privateData.js

@@ -1,6 +1,11 @@
+import isServer from "../utils/isServer.js";
 import { getRootContext } from "./rootContext.js";
-import { getPrivateDataSegments, isPrivateCollectionSegments } from "./rootScope.js";
+import { getPrivateDataSegments, isGlobalRootId, isPrivateCollectionSegments } from "./rootScope.js";
 import { arrayInsert as _arrayInsert, arrayMove as _arrayMove, arrayPop as _arrayPop, arrayPush as _arrayPush, arrayRemove as _arrayRemove, arrayShift as _arrayShift, arrayUnshift as _arrayUnshift, del as _del, set as _set, setReplace as _setReplace, stringInsertLocal as _stringInsertLocal, stringRemoveLocal as _stringRemoveLocal } from './dataTree.js';
+const warnedGlobalRootPrivateCollections = new Set();
+export function __resetPrivateDataWarningsForTests() {
+    warnedGlobalRootPrivateCollections.clear();
+}
 export function getPrivateDataRoot(rootId, create = false) {
     return getRootContext(rootId, create)?.getPrivateDataRoot();
 }
@@ -24,6 +29,7 @@ export function setPrivateData(rootId, logicalSegments, value) {
     const context = getRootContext(rootId, true);
     if (!context)
         return;
+    warnGlobalRootPrivateMutation(rootId, logicalSegments);
     const segments = getPrivateDataSegments(logicalSegments);
     _set(segments, value, context.getPrivateDataRoot(), getModelEventContext(rootId, logicalSegments));
 }
@@ -34,6 +40,7 @@ export function setReplacePrivateData(rootId, logicalSegments, value) {
     const context = getRootContext(rootId, true);
     if (!context)
         return;
+    warnGlobalRootPrivateMutation(rootId, logicalSegments);
     const segments = getPrivateDataSegments(logicalSegments);
     _setReplace(segments, value, context.getPrivateDataRoot(), getModelEventContext(rootId, logicalSegments));
 }
@@ -43,6 +50,7 @@ export function delPrivateData(rootId, logicalSegments, options = {}) {
     const context = getRootContext(rootId, false);
     if (!context)
         return;
+    warnGlobalRootPrivateMutation(rootId, logicalSegments);
     const segments = getPrivateDataSegments(logicalSegments);
     _del(segments, context.getPrivateDataRoot(), getModelEventContext(rootId, logicalSegments));
     pruneEmptyPrivateParents(context.getPrivateDataRoot(), context.getPrivateDataRawRoot(), segments, options);
@@ -108,8 +116,19 @@ function getRequiredPrivateContext(rootId, logicalSegments, methodName) {
     if (!isPrivateCollectionSegments(logicalSegments)) {
         throw Error(`${methodName} expects private collection segments`);
     }
+    warnGlobalRootPrivateMutation(rootId, logicalSegments);
     return getRootContext(rootId, true);
 }
+function warnGlobalRootPrivateMutation(rootId, logicalSegments) {
+    if (!isServer || !isGlobalRootId(rootId) || !isPrivateCollectionSegments(logicalSegments))
+        return;
+    const collection = String(logicalSegments[0]);
+    if (warnedGlobalRootPrivateCollections.has(collection))
+        return;
+    warnedGlobalRootPrivateCollections.add(collection);
+    console.warn(`[teamplay] Writing to private collection "${collection}" on the global server root. ` +
+        'Use a request-scoped root, getRootSignal({ rootId }), or req.model for per-request private state.');
+}
 function getModelEventContext(rootId, logicalSegments) {
     return {
         rootId,

package/dist/orm/queryReadiness.d.ts

@@ -0,0 +1,13 @@
+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/{Compat/queryReadiness.js → queryReadiness.js}

@@ -1,12 +1,12 @@
-import { getRaw } from '../dataTree.js';
-import { getConnection } from "../connection.js";
-import { isMissingShareDoc } from '../missingDoc.js';
-import { QUERIES, HASH, PARAMS, COLLECTION_NAME, querySubscriptions } from '../Query.js';
-import { AGGREGATIONS, IS_AGGREGATION, aggregationSubscriptions } from '../Aggregation.js';
-import { getPrivateData, setPrivateData } from '../privateData.js';
-import { getRoot, ROOT_ID } from "../Root.js";
-import { isRootContextClosed } from "../rootContext.js";
-import { getScopedSignalHash, normalizeRootId } from "../rootScope.js";
+import { getRaw } from './dataTree.js';
+import { getConnection } from "./connection.js";
+import { isMissingShareDoc } from './missingDoc.js';
+import { QUERIES, HASH, PARAMS, COLLECTION_NAME, querySubscriptions } from './Query.js';
+import { AGGREGATIONS, IS_AGGREGATION, aggregationSubscriptions } from './Aggregation.js';
+import { getPrivateData, setPrivateData } from './privateData.js';
+import { getRoot, ROOT_ID } from "./Root.js";
+import { isRootContextClosed } from "./rootContext.js";
+import { getScopedSignalHash, normalizeRootId } from "./rootScope.js";
 let imperativeQueryReadyTimeoutMs = 1000;
 export function isQueryReady(collection, idsSegments, docsSegments, extraSegments, aggregationSegments, isAggregate, hasExtraResult) {
     if (hasExtraResult) {
@@ -157,7 +157,7 @@ function createImperativeQueryReadinessError($query, timeoutMs) {
         }
     }
     return Error(`
-    Compat query did not fully materialize within ${timeoutMs}ms.
+    Query did not fully materialize within ${timeoutMs}ms.
       Collection: ${collection}
       Params: ${JSON.stringify(params)}
       Hash: ${hash}

package/dist/orm/reaction.d.ts

@@ -0,0 +1,11 @@
+export interface ReactionOptions {
+    lazy?: boolean;
+    debugger?: Function;
+    scheduler?: (run: () => unknown) => unknown;
+    onError?: (error: unknown) => unknown;
+}
+export interface ReactionHandle {
+    dispose: () => void;
+}
+export declare function reaction(fn: () => unknown, options?: ReactionOptions): ReactionHandle;
+export default reaction;

package/dist/orm/reaction.js

@@ -0,0 +1,47 @@
+import { observe, unobserve } from '@nx-js/observer-util';
+import { scheduleReaction } from './batchScheduler.js';
+export function reaction(fn, options = {}) {
+    if (typeof fn !== 'function')
+        throw Error('reaction() expects a function');
+    let disposed = false;
+    let pendingReactionFn;
+    function runReaction(runner) {
+        if (disposed)
+            return;
+        try {
+            return runner();
+        }
+        catch (error) {
+            if (typeof options.onError === 'function')
+                return options.onError(error);
+            throw error;
+        }
+    }
+    const scheduledRun = () => {
+        if (!pendingReactionFn)
+            return;
+        return runReaction(pendingReactionFn);
+    };
+    const runner = observe(fn, {
+        lazy: true,
+        debugger: options.debugger,
+        scheduler: (reactionFn) => {
+            pendingReactionFn = reactionFn;
+            if (typeof options.scheduler === 'function')
+                return options.scheduler(scheduledRun);
+            scheduleReaction(scheduledRun);
+        }
+    });
+    if (!options.lazy)
+        runReaction(runner);
+    return {
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            pendingReactionFn = undefined;
+            unobserve(runner);
+        }
+    };
+}
+export default reaction;

package/dist/orm/rootContext.d.ts

@@ -2,18 +2,9 @@ import type { PathSegment } from './types/path.js';
 type RootId = string | null | undefined;
 type DataTree = Record<string | number, unknown>;
 type RuntimeKind = 'query' | 'aggregation';
-type ModelEventStore = Map<string, unknown>;
-type ActiveRefEntry = {
-    stop?: () => void;
-};
 interface RootContextOptions {
     fetchOnly?: boolean;
 }
-interface ModelListeners {
-    change: ModelEventStore;
-    all: ModelEventStore;
-    [eventName: string]: ModelEventStore;
-}
 export interface DirectDocSubscriptionEntry {
     segments: PathSegment[];
     count: number;
@@ -24,15 +15,11 @@ export default class RootContext {
     fetchOnly: boolean;
     privateDataRaw: DataTree;
     privateData: DataTree;
-    readonly refLinks: Map<string, unknown>;
-    readonly activeRefs: Map<string, ActiveRefEntry>;
-    readonly modelListeners: ModelListeners;
     readonly queryRuntimeHashes: Set<string>;
     readonly aggregationRuntimeHashes: Set<string>;
     readonly signalHashes: Set<string>;
     readonly directDocSubscriptions: Map<string, DirectDocSubscriptionEntry>;
     constructor(rootId: RootId, { fetchOnly }?: RootContextOptions);
-    getModelEventStore(eventName: string, create?: boolean): ModelEventStore;
     getFetchOnly(): boolean;
     setFetchOnly(value: boolean): void;
     getPrivateDataRoot(): DataTree;
@@ -48,9 +35,6 @@ export default class RootContext {
     unregisterSignalHash(signalHash: string | null | undefined): void;
     registerDirectDocSubscription(hash: string | null | undefined, segments: readonly PathSegment[], token?: unknown): void;
     unregisterDirectDocSubscription(hash: string | null | undefined, token?: unknown): void;
-    resetRefs(): void;
-    resetActiveRefs(): void;
-    resetModelListeners(): void;
     resetRuntimeHashes(): void;
     resetPrivateData(): void;
     resetSignalHashes(): void;

package/dist/orm/rootContext.js

@@ -12,12 +12,6 @@ export default class RootContext {
     fetchOnly;
     privateDataRaw;
     privateData;
-    refLinks = new Map();
-    activeRefs = new Map();
-    modelListeners = {
-        change: new Map(),
-        all: new Map()
-    };
     queryRuntimeHashes = new Set();
     aggregationRuntimeHashes = new Set();
     signalHashes = new Set();
@@ -28,14 +22,6 @@ export default class RootContext {
         this.privateDataRaw = {};
         this.privateData = observable(this.privateDataRaw);
     }
-    getModelEventStore(eventName, create = false) {
-        let store = this.modelListeners[eventName];
-        if (!store && create) {
-            store = new Map();
-            this.modelListeners[eventName] = store;
-        }
-        return store;
-    }
     getFetchOnly() {
         return !!this.fetchOnly;
     }
@@ -124,17 +110,6 @@ export default class RootContext {
         if (entry.count === 0)
             this.directDocSubscriptions.delete(hash);
     }
-    resetRefs() {
-        this.refLinks.clear();
-    }
-    resetActiveRefs() {
-        this.activeRefs.clear();
-    }
-    resetModelListeners() {
-        for (const store of Object.values(this.modelListeners)) {
-            store.clear();
-        }
-    }
     resetRuntimeHashes() {
         this.queryRuntimeHashes.clear();
         this.aggregationRuntimeHashes.clear();
@@ -151,9 +126,6 @@ export default class RootContext {
     }
     isRuntimeEmpty() {
         return (isPlainObjectEmpty(this.privateData) &&
-            this.refLinks.size === 0 &&
-            this.activeRefs.size === 0 &&
-            Object.values(this.modelListeners).every(store => store.size === 0) &&
             this.queryRuntimeHashes.size === 0 &&
             this.aggregationRuntimeHashes.size === 0 &&
             this.signalHashes.size === 0 &&

package/dist/orm/signalMetadata.js

@@ -36,14 +36,14 @@ export function getSignalId($signal, rootId, readPath) {
         throw Error('Can\'t get the id of a collection');
     if (isDirectPublicDocumentSegments(segments))
         return getLeafId(segments);
+    if (segments[0] === AGGREGATIONS && segments.length === 3) {
+        return getAggregationDocId(segments, rootId, readPath);
+    }
     if (readPath) {
         const valueId = getValueIdFromPaths(segments, readPath);
         if (valueId.found)
             return valueId.id;
     }
-    if (segments[0] === AGGREGATIONS && segments.length === 3) {
-        return getAggregationDocId(segments, rootId);
-    }
     return getLeafId(segments);
 }
 export function getSignalCollection($signal) {

package/dist/orm/signalReads.js

@@ -1,4 +1,4 @@
-import { AGGREGATIONS, IS_AGGREGATION } from './Aggregation.js';
+import { AGGREGATIONS, IS_AGGREGATION, getAggregationCollectionName, getAggregationRowId } from './Aggregation.js';
 import { HASH, IS_QUERY, QUERIES } from './Query.js';
 import { SEGMENTS } from "./signalSymbols.js";
 export function readSignalValue($signal, context, method, rawMethod) {
@@ -41,7 +41,8 @@ export function getSignalIds($signal, context) {
         const docs = context.readPrivateData(rootId, $signal[SEGMENTS], false);
         if (!Array.isArray(docs))
             return [];
-        return docs.map(getAggregationRowId).filter(isString);
+        const collectionName = getAggregationCollectionName($signal[SEGMENTS]);
+        return docs.map(doc => getAggregationRowId(doc, collectionName)).filter(isString);
     }
     context.error('Signal.getIds() can only be used on query signals or aggregation signals. ' +
         'Received a regular signal: ' + JSON.stringify($signal[SEGMENTS]));
@@ -55,13 +56,6 @@ export function isAggregationValueSignal($signal) {
     const segments = $signal[SEGMENTS];
     return segments.length >= 2 && segments[0] === AGGREGATIONS;
 }
-function getAggregationRowId(doc) {
-    const row = doc;
-    if (typeof row?._id === 'string')
-        return row._id;
-    if (typeof row?.id === 'string')
-        return row.id;
-}
 function isString(value) {
     return typeof value === 'string';
 }

package/dist/orm/signalStorageMutations.d.ts

@@ -3,7 +3,6 @@ type MaybePromise<TValue> = TValue | Promise<TValue>;
 export interface SignalStorageMutationContext<TSignal> {
     getOwningRootId: ($signal: TSignal) => string | undefined;
     isPublicCollection: (segment: PathSegment | undefined) => boolean;
-    isPrivateMutationForbidden: () => boolean;
 }
 export interface SignalStorageMutationHandlers<TResult> {
     public: (segments: PathSegment[]) => MaybePromise<TResult>;
@@ -14,5 +13,4 @@ export interface SignalStorageMutationResult<TResult> {
     value: TResult | undefined;
 }
 export declare function runSignalStorageMutation<TSignal, TResult>($signal: TSignal, context: SignalStorageMutationContext<TSignal>, segments: PathSegment[], handlers: SignalStorageMutationHandlers<TResult>): Promise<SignalStorageMutationResult<TResult>>;
-export declare function ensurePrivateMutationAllowed<TSignal>(context: Pick<SignalStorageMutationContext<TSignal>, 'isPrivateMutationForbidden'>): void;
 export {};

package/dist/orm/signalStorageMutations.js

@@ -10,17 +10,8 @@ export async function runSignalStorageMutation($signal, context, segments, handl
             value: await handlers.public(segments)
         };
     }
-    ensurePrivateMutationAllowed(context);
     return {
         skipped: false,
         value: await handlers.private(context.getOwningRootId($signal), segments)
     };
 }
-export function ensurePrivateMutationAllowed(context) {
-    if (!context.isPrivateMutationForbidden())
-        return;
-    throw Error(`
-    Can't modify private collections data when 'publicOnly' is enabled.
-    On the server you can only work with public collections.
-  `);
-}

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/orm/signalValueMutations.d.ts

@@ -1,4 +1,4 @@
-import { type SignalStorageMutationContext } from './signalStorageMutations.js';
+import type { SignalStorageMutationContext } from './signalStorageMutations.js';
 import { SEGMENTS } from './signalSymbols.js';
 import type { PathSegment } from './types/path.js';
 export interface SignalValueMutationOwner {

package/dist/orm/signalValueMutations.js

@@ -1,5 +1,4 @@
 import { getIdFieldsForSegments, isIdFieldPath, isPublicDocPath, normalizeIdFields } from "./idFields.js";
-import { ensurePrivateMutationAllowed } from "./signalStorageMutations.js";
 import { SEGMENTS } from "./signalSymbols.js";
 export async function setSignalValue($signal, context, value) {
     const segments = $signal[SEGMENTS];
@@ -15,7 +14,6 @@ export async function setSignalValue($signal, context, value) {
         await context.setPublicDoc(segments, nextValue);
         return;
     }
-    ensurePrivateMutationAllowed(context);
     context.setPrivateData(context.getOwningRootId($signal), segments, nextValue);
 }
 export async function deleteSignalValue($signal, context) {
@@ -31,6 +29,5 @@ export async function deleteSignalValue($signal, context) {
         await context.deletePublicDoc(segments);
         return;
     }
-    ensurePrivateMutationAllowed(context);
     context.deletePrivateData(context.getOwningRootId($signal), segments);
 }

package/dist/orm/sub.d.ts

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