akanjs 3.0.0-alpha.91 → 3.0.0-alpha.92

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.91",
+  "version": "3.0.0-alpha.92",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/resolver/signal.resolver.ts

@@ -374,9 +374,11 @@ export class SignalResolver {
                 `and opening it would put every model on a live socket by default.`,
             );
           SignalResolver.#assertLiveSort(refName, key, sliceInfo);
+          SignalResolver.#assertLivePauseOn(refName, key, sliceInfo);
           const liveKey = `${refName}Live${capitalizedKey}`;
+
           const liveBuilder = (builder as any).pubsub(Any, {
-            guards: sliceCls.getGuards,
+            ...sliceInfo.signalOption,
             mcp: false,
             live: {
               refName,
@@ -384,6 +386,7 @@ export class SignalResolver {
               sort: sliceInfo.liveOption.sort,
               fallback: sliceInfo.liveOption.fallback,
               payload: sliceInfo.liveOption.payload,
+              pauseOn: sliceInfo.liveOption.pauseOn,
             } satisfies LiveEndpointOption,
           });
           endpointObj[liveKey] = liveBuilder
@@ -482,6 +485,44 @@ export class SignalResolver {
       }
     }
   }
+  /** Refuses a subscribe carrying an argument the slice named in `pauseOn`, naming the argument it refused on. */
+  static #assertNotPaused(
+    key: string,
+    liveOption: LiveEndpointOption,
+    endpointInfo: EndpointInfo,
+    context: SignalContext,
+  ) {
+    for (const name of liveOption.pauseOn) {
+      const idx = endpointInfo.args.findIndex((arg) => arg.name === name);
+      if (idx < 0 || context.args[idx] == null) continue;
+      throw new Error(
+        `Live room "${key}" is paused while "${name}" carries a value: the slice declared it in ` +
+          `.live({ pauseOn }), so this window updates by refetching instead of subscribing.`,
+      );
+    }
+  }
+  /**
+   * That every argument `pauseOn` names is one this slice has, and one that can actually be empty.
+   *
+   * A name that is not an argument would do nothing at all, and a `param` — which is never nullable, so it is
+   * present on every call — would switch the room off for good rather than while a box is filled. Both are the
+   * kind of mistake whose only symptom is a list that never updates, so neither is allowed to boot.
+   */
+  static #assertLivePauseOn(refName: string, key: string, sliceInfo: SliceInfo) {
+    for (const name of sliceInfo.liveOption?.pauseOn ?? []) {
+      const arg = sliceInfo.args.find((candidate) => candidate.name === name);
+      if (!arg)
+        throw new Error(
+          `Live slice "${refName}.${key}" declares pauseOn "${name}", which is not one of its arguments ` +
+            `(${sliceInfo.args.map((candidate) => candidate.name).join(", ") || "none"}).`,
+        );
+      if (!arg.option?.nullable)
+        throw new Error(
+          `Live slice "${refName}.${key}" declares pauseOn "${name}", which is a required ${arg.type} and is ` +
+            `therefore always present — the room would never open. Only a nullable argument can pause live sync.`,
+        );
+    }
+  }
   /**
    * The model's field metadata, which membership routing reads for one thing: whether a path is an array, because
    * a bare value on an array field means membership rather than equality.
@@ -649,6 +690,8 @@ export class SignalResolver {
 
               const requestRoomId = context.getRoomId(key);
               if (subscribe) {
+
+                if (liveOption) SignalResolver.#assertNotPaused(key, liveOption, endpointInfo, context);
                 const query = await context.exec();
                 const roomId = liveOption ? context.getLiveRoomId(key) : requestRoomId;
                 if (liveOption)

package/signal/serializer/fetch.serializer.ts

@@ -110,7 +110,14 @@ export class FetchSerializer {
       ...(sliceInfo.signalOption.path ? { path: sliceInfo.signalOption.path } : {}),
       ...(guards?.length ? { guards } : {}),
       ...(sliceInfo.signalOption.mcp === false ? { mcp: false as const } : {}),
-      ...(sliceInfo.liveOption ? { live: { sort: sliceInfo.liveOption.sort } } : {}),
+      ...(sliceInfo.liveOption
+        ? {
+            live: {
+              sort: sliceInfo.liveOption.sort,
+              ...(sliceInfo.liveOption.pauseOn.length ? { pauseOn: sliceInfo.liveOption.pauseOn } : {}),
+            },
+          }
+        : {}),
     };
   }
 

package/signal/sliceInfo.ts

@@ -27,7 +27,7 @@ import type { CnstFull, CnstInput, CnstInsight, CnstLight, DbFilter, SignalOptio
  * What a slice declares when it opts into live sync. Nothing here is required — `.live()` on its own is the whole
  * opt-in, and every default below is the conservative reading.
  */
-export interface LiveSliceOption {
+export interface LiveSliceOption<ArgName extends string = string> {
   /**
    * The sort keys a client may reproduce well enough to place a row itself. Anything else falls back to a refetch,
    * because the client would otherwise have to guess where a new row goes.
@@ -45,12 +45,28 @@ export interface LiveSliceOption {
   fallback?: "invalidate";
   /** `light` sends the row and costs nothing to apply; `id` sends the id alone for a room where the row is bulky. */
   payload?: "light" | "id";
+  /**
+   * The arguments that switch live sync off for as long as they carry a value, named for this slice.
+   *
+   * A filter often builds a different query shape depending on what it was handed — `search ? q.search(text) : {}`
+   * is the common one — so the same slice is routable blank and unroutable with text in the box. Naming the
+   * argument makes that explicit: the client opens no room while it is filled and the window updates by
+   * refetching, which is what a slice with no `.live()` at all does. Clearing it opens the room again.
+   *
+   * Only a nullable argument can be named, which in practice means a `search`: a `param` is always present, so
+   * naming one would switch live off for good. That is refused at boot rather than left to be discovered.
+   *
+   * This is not `fallback`. `fallback: "invalidate"` keeps the room and gives up precision — every write on the
+   * model tells the room to refetch. `pauseOn` gives up the room and keeps precision everywhere else.
+   */
+  pauseOn?: ArgName[];
 }
 
 export interface ResolvedLiveSliceOption {
   sort: string[];
   fallback: "invalidate" | null;
   payload: "light" | "id";
+  pauseOn: string[];
 }
 
 export class SliceInfo<
@@ -193,13 +209,14 @@ export class SliceInfo<
     >;
   }
   /** Opts this slice into live sync. Declaring nothing at all is what keeps a slice out of it entirely. */
-  live(option: LiveSliceOption = {}) {
+  live(option: LiveSliceOption<ArgNames[number]> = {}) {
     if (this.execFn) throw new Error("Query function is already set");
     if (this.liveOption) throw new Error("Live option is already set");
     this.liveOption = {
       sort: option.sort ?? ["latest"],
       fallback: option.fallback ?? null,
       payload: option.payload ?? "light",
+      pauseOn: (option.pauseOn as string[] | undefined) ?? [],
     };
     return this;
   }

package/signal/types.ts

@@ -69,6 +69,8 @@ export interface LiveEndpointOption {
   sort: string[];
   fallback: "invalidate" | null;
   payload: "light" | "id";
+  /** Room arguments that must be empty for the room to exist at all. Enforced here as well as in the client. */
+  pauseOn: string[];
 }
 
 export interface SignalOption<Response = any, Nullable extends boolean = false, _Key = keyof UnCls<Response>>
@@ -143,9 +145,10 @@ interface SerializedSignalOption {
 export interface SerializedSlice extends SerializedSignalOption {
   /**
    * Present when the slice declared `.live()`. `sort` is the allowlist of sort keys a subscriber may place a new
-   * row under itself; on any other sort an insertion refetches instead of guessing where the row goes.
+   * row under itself; on any other sort an insertion refetches instead of guessing where the row goes. `pauseOn`
+   * names the arguments that switch the room off while they carry a value, and travels only when there are any.
    */
-  live?: { sort: string[] };
+  live?: { sort: string[]; pauseOn?: string[] };
 }
 
 export interface SerializedReturns {

package/store/action.ts

@@ -1018,6 +1018,10 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
     const requests = new SliceRequest();
 
     let liveWatch: { signature: string; dispose: () => void } | null = null;
+    
+    const livePauseIdxs = (slice.live?.pauseOn ?? [])
+      .map((name) => slice.args.findIndex((arg) => arg.name === name))
+      .filter((idx) => idx >= 0);
     const namesOfSlice: { [key in SliceActionKey | SliceStateKey | "modelList"]: string } = {
       defaultModel: SliceName.replace(names.Model, names.defaultModel),
       modelInsight: sliceName.replace(names.model, names.modelInsight),
@@ -1395,12 +1399,14 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
       [namesOfSlice.watchLiveModel]: function (this: SetGet, queryArgs: unknown[] | null) {
         if (!slice.live) return;
         const args = queryArgs ? expandQueryArgs(normalizeQueryArgs(queryArgs, slice.args), slice.args) : null;
-        const signature = args ? JSON.stringify(args) : null;
+
+        const paused = !!args && livePauseIdxs.some((idx) => args[idx] != null);
+        const signature = args && !paused ? JSON.stringify(args) : null;
         if (liveWatch && signature !== liveWatch.signature) {
           liveWatch.dispose();
           liveWatch = null;
         }
-        if (!args || liveWatch) return;
+        if (!args || paused || liveWatch) return;
         const self = this as unknown as DynamicRecord;
         const apply = self[namesOfSlice.applyLiveModel] as (event: unknown) => void;
         const refresh = self[namesOfSlice.refreshModel] as (form: object) => Promise<void>;

package/types/signal/sliceInfo.d.ts

@@ -9,7 +9,7 @@ import type { CnstFull, CnstInput, CnstInsight, CnstLight, DbFilter, SignalOptio
  * What a slice declares when it opts into live sync. Nothing here is required — `.live()` on its own is the whole
  * opt-in, and every default below is the conservative reading.
  */
-export interface LiveSliceOption {
+export interface LiveSliceOption<ArgName extends string = string> {
     /**
      * The sort keys a client may reproduce well enough to place a row itself. Anything else falls back to a refetch,
      * because the client would otherwise have to guess where a new row goes.
@@ -27,11 +27,27 @@ export interface LiveSliceOption {
     fallback?: "invalidate";
     /** `light` sends the row and costs nothing to apply; `id` sends the id alone for a room where the row is bulky. */
     payload?: "light" | "id";
+    /**
+     * The arguments that switch live sync off for as long as they carry a value, named for this slice.
+     *
+     * A filter often builds a different query shape depending on what it was handed — `search ? q.search(text) : {}`
+     * is the common one — so the same slice is routable blank and unroutable with text in the box. Naming the
+     * argument makes that explicit: the client opens no room while it is filled and the window updates by
+     * refetching, which is what a slice with no `.live()` at all does. Clearing it opens the room again.
+     *
+     * Only a nullable argument can be named, which in practice means a `search`: a `param` is always present, so
+     * naming one would switch live off for good. That is refused at boot rather than left to be discovered.
+     *
+     * This is not `fallback`. `fallback: "invalidate"` keeps the room and gives up precision — every write on the
+     * model tells the room to refetch. `pauseOn` gives up the room and keeps precision everywhere else.
+     */
+    pauseOn?: ArgName[];
 }
 export interface ResolvedLiveSliceOption {
     sort: string[];
     fallback: "invalidate" | null;
     payload: "light" | "id";
+    pauseOn: string[];
 }
 export declare class SliceInfo<RefName extends string = string, Input = any, Full = any, Light = any, Insight = any, Filter extends FilterInstance = any, Srvs extends {
     [key: string]: any;
@@ -56,7 +72,7 @@ export declare class SliceInfo<RefName extends string = string, Input = any, Ful
     search<ArgName extends string, ExplicitType = unknown, Arg extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, _ArgType = unknown extends ExplicitType ? FieldToValue<Arg> : ExplicitType, _ClientArg = PurifiedModel<_ArgType>, _ServerArg = DocumentModel<_ArgType>>(name: ArgName, arg: Arg, option?: Omit<EndpointArgProps, "nullable">): SliceInfo<RefName, Input, Full, Light, Insight, Filter, Srvs, [...ArgNames, ArgName], [...Args, arg?: _ClientArg | null], InternalArgs, [...ServerArgs, arg: _ServerArg | undefined]>;
     with<ArgType, Optional extends boolean = false>(argRef: InternalArgCls<ArgType>, option?: InternalArgProps<Optional>): SliceInfo<RefName, Input, Full, Light, Insight, Filter, Srvs, ArgNames, Args, [...InternalArgs, arg: NonNullable<ArgType> | (Optional extends true ? null : never)], ServerArgs>;
     /** Opts this slice into live sync. Declaring nothing at all is what keeps a slice out of it entirely. */
-    live(option?: LiveSliceOption): this;
+    live(option?: LiveSliceOption<ArgNames[number]>): this;
     exec(query: (this: {
         [K in keyof Srvs as K extends string ? Uncapitalize<K> : never]: Srvs[K];
     }, ...args: [...ServerArgs, ...InternalArgs]) => PromiseOrObject<QueryOf<DocumentModel<Full>>>): this;

package/types/signal/types.d.ts

@@ -60,6 +60,8 @@ export interface LiveEndpointOption {
     sort: string[];
     fallback: "invalidate" | null;
     payload: "light" | "id";
+    /** Room arguments that must be empty for the room to exist at all. Enforced here as well as in the client. */
+    pauseOn: string[];
 }
 export interface SignalOption<Response = any, Nullable extends boolean = false, _Key = keyof UnCls<Response>> extends InitOption, TimerOption {
     nullable?: Nullable;
@@ -129,10 +131,12 @@ interface SerializedSignalOption {
 export interface SerializedSlice extends SerializedSignalOption {
     /**
      * Present when the slice declared `.live()`. `sort` is the allowlist of sort keys a subscriber may place a new
-     * row under itself; on any other sort an insertion refetches instead of guessing where the row goes.
+     * row under itself; on any other sort an insertion refetches instead of guessing where the row goes. `pauseOn`
+     * names the arguments that switch the room off while they carry a value, and travels only when there are any.
      */
     live?: {
         sort: string[];
+        pauseOn?: string[];
     };
 }
 export interface SerializedReturns {

package/ui/Load/Units.tsx

@@ -161,12 +161,13 @@ function Render<RefName extends string, Light extends { id: string }>({
     loadedQueryArgs.current = initQueryArgs;
   }, [initSignature]);
 
+  const queryArgsSignature = JSON.stringify(storeUse[namesOfSlice.queryArgsOfModel]());
   useEffect(() => {
-    void storeDo[namesOfSlice.watchLiveModel](initQueryArgs);
+    void storeDo[namesOfSlice.watchLiveModel](storeGet<object[]>()[namesOfSlice.queryArgsOfModel] ?? initQueryArgs);
     return () => {
       void storeDo[namesOfSlice.watchLiveModel](null);
     };
-  }, [initSignature]);
+  }, [initSignature, queryArgsSignature]);
 
   useEffect(() => {
     const modelStaleAt = storeGet<Date>()[namesOfSlice.modelStaleAt];