@arcote.tech/arc 0.7.15 → 0.7.17

package/dist/model/live-query/diff.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Diff between two query results → positional deltas for the wire.
+ *
+ * The server re-executes a subscribed query and diffs the previous result
+ * against the new one. For lists of items with `_id` it produces minimal
+ * `set`/`delete` changes WITH target positions — the client applies them
+ * blindly (remove-by-id + splice at index), so result order is always the
+ * server's order (only the query handler knows its orderBy).
+ *
+ * Correctness over cleverness: the deltas are verified by simulating their
+ * application; any mismatch falls back to a full snapshot.
+ */
+export type QueryResultChange = {
+    type: "set";
+    id: string;
+    item: any;
+    index: number;
+} | {
+    type: "delete";
+    id: string;
+};
+export type QueryDiff = {
+    kind: "none";
+} | {
+    kind: "changes";
+    changes: QueryResultChange[];
+} | {
+    kind: "snapshot";
+    result: any;
+};
+export declare function diffResults(prev: any, next: any): QueryDiff;
+/**
+ * Apply positional deltas to a result list — the exact client-side
+ * algorithm (exported so client cache and tests share one implementation):
+ * all deletes first, then sets in ascending index order.
+ */
+export declare function applyQueryChanges(result: Array<{
+    _id: string;
+}>, changes: QueryResultChange[]): Array<{
+    _id: string;
+}>;
+//# sourceMappingURL=diff.d.ts.map

package/dist/model/live-query/diff.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=diff.test.d.ts.map

package/dist/model/live-query/index.d.ts

@@ -1,2 +1,4 @@
 export * from "./live-query";
+export * from "./live-query-subscription";
+export * from "./diff";
 //# sourceMappingURL=index.d.ts.map

package/dist/model/live-query/live-query-subscription.d.ts

@@ -0,0 +1,66 @@
+/**
+ * LiveQuery — a server-side query subscription that owns its deltas.
+ *
+ * The SAME query (any descriptor: bare view find or custom clientQuery
+ * handler) is executed with an ObservableDataStorage wrapped around the
+ * real storage. Every `find` the handler makes — already merged with token
+ * restrictions by ScopedStore — gets tracked. After each store commit,
+ * `resolveQueryChange` updates the tracked results in memory; when any of
+ * them changed, the descriptor is re-executed AGAINST THE CACHE (0 SQL)
+ * and the new result is diffed against the previous one.
+ *
+ * The transport layer (WS) only forwards `onUpdate` payloads — all query
+ * logic (filtering, scoping, ordering) lives here, in the query layer.
+ */
+import { type ContextDescriptor } from "../context-accessor";
+import type { ModelLike } from "../model-like";
+import { type QueryResultChange } from "./diff";
+export type LiveQueryUpdate = {
+    type: "changes";
+    changes: QueryResultChange[];
+} | {
+    type: "snapshot";
+    result: any;
+};
+export declare class LiveQuery {
+    private readonly model;
+    private readonly descriptor;
+    private readonly scope;
+    private readonly rawToken;
+    private readonly onUpdate;
+    private observable;
+    private adapters;
+    private lastResult;
+    private scheduled;
+    private running;
+    private rerunRequested;
+    private stopped;
+    constructor(model: ModelLike<any>, descriptor: ContextDescriptor, scope: string, rawToken: string | null, onUpdate: (update: LiveQueryUpdate) => void);
+    /**
+     * Execute the descriptor with tracking and return the initial result.
+     */
+    start(): Promise<any>;
+    /**
+     * Close the initial-execute window: the store listener is registered
+     * before the read transaction, but trackQuery happens after the await —
+     * a commit in between could slip past the tracked entry. One forced
+     * re-execute (cache-backed, no SQL when nothing changed) diffs out any
+     * missed delta.
+     *
+     * Call AFTER the initial result has been delivered (e.g. the snapshot
+     * message was sent) — otherwise the catch-up delta could overtake it.
+     */
+    flush(): void;
+    /**
+     * Stop tracking — unsubscribes all store listeners.
+     */
+    stop(): void;
+    /**
+     * Coalesce re-executes: a single commit can touch multiple stores and
+     * fire onChange several times — one microtask handles them all. A commit
+     * landing DURING a re-execute requests another pass afterwards.
+     */
+    private schedule;
+    private run;
+}
+//# sourceMappingURL=live-query-subscription.d.ts.map

package/dist/model/scoped-model.d.ts

@@ -21,7 +21,15 @@ export declare class ScopedModel<Context extends ArcContextAny> implements Model
     private readonly scopedAdapters;
     private tokenListeners;
     constructor(parent: ModelLike<Context>, scopeName: string);
-    setToken(token: string | null): void;
+    /**
+     * Set this scope's token. Returns a promise that resolves when the platform
+     * module loader has synced the chunks for the new token state (so routes in
+     * newly-gated modules exist before the caller navigates). With no module-sync
+     * provider registered (server, SSR, tests, app-without-platform) it resolves
+     * immediately — preserving the historical synchronous semantics for the many
+     * server-side `setToken(rawToken)` callers that ignore the return value.
+     */
+    setToken(token: string | null): Promise<void>;
     getToken(): string | null;
     getDecoded(): DecodedToken | null;
     getParams(): Record<string, any> | null;

package/dist/streaming/index.d.ts

@@ -1,4 +1,4 @@
 export { StreamingQueryCache } from "./streaming-query-cache";
-export type { CacheChangeListener, StreamingQueryCacheStore, } from "./streaming-query-cache";
+export type { QuerySubscriptionHandle } from "./streaming-query-cache";
 export { StreamingEventPublisher } from "./streaming-event-publisher";
 //# sourceMappingURL=index.d.ts.map

package/dist/streaming/streaming-event-publisher.d.ts

@@ -1,35 +1,33 @@
 /**
  * StreamingEventPublisher - Event publisher for streaming mode (no local database)
  *
- * When events are emitted:
- * 1. Apply to local cache (optimistic update)
- * 2. Send to server via EventWire
- *
- * This enables instant UI updates while syncing with server.
+ * When events are emitted locally (client-side mutate handlers), they are
+ * sent to the server via EventWire; the server commits them and pushes the
+ * resulting query deltas back through live query subscriptions. No local
+ * optimistic apply — the client holds query RESULTS, not view data, so it
+ * cannot compute how an event affects a custom query handler's output.
  */
 import type { EventPublisher, EventWithSyncStatus } from "../adapters/event-publisher";
 import type { EventWire } from "../adapters/event-wire";
 import type { ArcEventAny } from "../context-element/event/event";
 import type { ArcEventInstance } from "../context-element/event/instance";
 import type { ArcViewAny } from "../context-element/view/view";
-import type { StreamingQueryCache } from "./streaming-query-cache";
 /**
  * StreamingEventPublisher
  */
 export declare class StreamingEventPublisher implements EventPublisher {
-    private readonly cache;
     private readonly eventWire;
     private views;
     private subscribers;
-    constructor(cache: StreamingQueryCache, eventWire: EventWire);
+    constructor(eventWire: EventWire);
     /**
      * Register views for event handling
      */
     registerViews(views: ArcViewAny[]): void;
     /**
      * Publish an event
-     * 1. Apply to local cache (optimistic)
-     * 2. Send to server
+     * 1. Notify local subscribers
+     * 2. Send to server (server commits → live query deltas come back)
      */
     publish(event: ArcEventInstance<ArcEventAny>): Promise<void>;
     /**

package/dist/streaming/streaming-query-cache.d.ts

@@ -1,113 +1,52 @@
 /**
- * StreamingQueryCache - Lightweight in-memory cache for streaming mode
+ * StreamingQueryCache - per-query result cache for streaming mode
  *
- * Used when client connects without local database (no SQLite/IndexedDB).
- * Holds per-(scope, view) replicas of the token's slice of each view:
- * the server sends a full `view-snapshot` on subscribe, then incremental
- * `view-changes` deltas. All queries resolve locally against the replica.
+ * Used when the client connects without a local database. Each unique
+ * (scope, descriptor) gets ONE live subscription over the EventWire:
+ * the server executes the query with tracking (LiveQuery), sends a full
+ * `query-snapshot`, then positional `query-changes` deltas. The client
+ * applies deltas blindly — ALL query logic (filtering, scoping, ordering)
+ * lives on the server, in the query layer.
  *
  * Features:
- * - Stores view data in memory (Map-based), keyed by `${scope}:${viewName}`
- * - Supports reactive queries with listeners (ListenerEvent[] | null)
- * - Applies view handlers for optimistic local event emission
- * - Deduplicates WS subscriptions (one stream per scope:view)
+ * - Dedup: many components with the same query share one subscription
+ *   (refCount + UNSUBSCRIBE_DELAY grace window for quick remounts)
+ * - Snapshot/delta application with listener notifications
+ * - Scope invalidation on token change (workspace switch / re-auth)
  */
 import type { EventWire } from "../adapters/event-wire";
-import type { ArcEventAny } from "../context-element/event/event";
-import type { ArcEventInstance } from "../context-element/event/instance";
-import type { ArcViewAny } from "../context-element/view/view";
-import type { FindOptions } from "../data-storage/find-options";
-import type { ListenerEvent } from "../data-storage/data-storage.abstract";
-/**
- * Cache change listener receives ListenerEvent[] for incremental changes,
- * or null for bulk replacement (setAll) which requires full re-query.
- */
-export type CacheChangeListener = (events: ListenerEvent<any>[] | null) => void;
-export interface StreamingQueryCacheStore<Item extends {
-    _id: string;
-}> {
-    find(options?: FindOptions<Item>): Item[];
-    findOne(where?: Record<string, any>): Item | undefined;
-    subscribe(listener: CacheChangeListener): () => void;
-    hasData(): boolean;
+import type { ContextDescriptor } from "../model/context-accessor";
+export interface QuerySubscriptionHandle {
+    /** Current state — stable shape for React reads. */
+    read(): {
+        result: any;
+        loading: boolean;
+    };
+    unsubscribe(): void;
 }
-/**
- * StreamingQueryCache - Main cache class
- */
 export declare class StreamingQueryCache {
-    private stores;
-    private views;
-    private activeStreams;
-    private pendingUnsubscribes;
+    private entries;
     private static UNSUBSCRIBE_DELAY_MS;
-    /** Replica key — restrictions depend on the scope's token, so two scopes
-     *  subscribing the same view must hold separate replicas. */
-    private storeKey;
-    /**
-     * Register views that this cache will handle
-     */
-    registerViews(views: ArcViewAny[]): void;
-    /**
-     * Get the replica store for a view in a given scope
-     */
-    getStore<Item extends {
-        _id: string;
-    }>(viewName: string, scope?: string): StreamingQueryCacheStore<Item>;
-    /**
-     * Check if a replica has received its snapshot
-     */
-    hasData(viewName: string, scope?: string): boolean;
-    /**
-     * Register an active stream for a key (increment ref count if exists)
-     * Returns object with unsubscribe function and whether stream was reused
-     */
-    registerStream(key: string, createStream: () => {
-        unsubscribe: () => void;
-    }): {
-        unsubscribe: () => void;
-        wasReused: boolean;
-    };
-    /**
-     * Unregister from a stream. When refCount hits 0, delays actual WS
-     * unsubscribe by UNSUBSCRIBE_DELAY_MS. If re-registered within the
-     * window, the existing subscription is reused (cache serves immediately).
-     */
-    private unregisterStream;
-    /**
-     * Subscribe to a view replica via WebSocket with deduplication.
-     * Multiple callers share a single WS subscription per (scope, view).
-     * Snapshot → setAll (listeners get null → full re-query);
-     * deltas → applyChanges (listeners get ListenerEvent[] → local resolve).
-     * Returns unsubscribe function that decrements refcount.
-     */
-    subscribeView(viewName: string, eventWire: EventWire, scope?: string): () => void;
+    private entryKey;
     /**
-     * Force-close every active stream of `scope`. Called when a scope's token
-     * changes (workspace switch / re-auth) so the next `subscribeView()`
-     * creates a fresh WS subscription with the new token instead of reusing
-     * the stale one (which would keep pumping data filtered by the previous
-     * token until the page reload).
-     *
-     * Bypasses both `refCount` (other subscribers still mounted) and the
-     * UNSUBSCRIBE_DELAY_MS grace window — both became invalid the moment the
-     * token changed. React's `useQuery` re-subscribes immediately afterwards
-     * via the `subKey` change (token is in the key), getting a fresh stream.
-     *
-     * Bonus: each affected store is also cleared so any in-progress render
-     * that reads `store.find()` between `setToken` and the new WS snapshot
-     * arriving gets `[]` rather than stale rows from the previous workspace.
+     * Subscribe to a live query. Identical (scope, descriptor) pairs share
+     * one WS subscription; the last unsubscriber tears it down after a grace
+     * window (instant remounts reuse the cached result without a snapshot
+     * round-trip).
      */
-    invalidateScope(scope: string): void;
+    subscribe(descriptor: ContextDescriptor, scope: string, eventWire: EventWire, onChange: () => void): QuerySubscriptionHandle;
     /**
-     * Apply an event to update view state — optimistic local update for
-     * mutations executed client-side. Runs view handlers against every
-     * existing scope-replica of the view (the authoritative per-scope delta
-     * arrives from the server afterwards; sets/deletes are idempotent).
+     * Force-drop every cached query of `scope`. Called when the scope's token
+     * changes (workspace switch / re-auth) — cached results and the WS
+     * subscriptions behind them were computed with the previous token.
+     * React's `useQuery` re-subscribes immediately afterwards (token is part
+     * of its subscription key), getting fresh snapshots.
      */
-    applyEvent(event: ArcEventInstance<ArcEventAny>): Promise<void>;
+    invalidateScope(scope: string, eventWire?: EventWire): void;
     /**
-     * Clear all cached data and close all streams
+     * Clear all cached queries and tear down their subscriptions.
      */
-    clear(): void;
+    clear(eventWire?: EventWire): void;
+    private notify;
 }
 //# sourceMappingURL=streaming-query-cache.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arcote.tech/arc",
   "type": "module",
-  "version": "0.7.15",
+  "version": "0.7.17",
   "private": false,
   "author": "Przemysław Krasiński [arcote.tech]",
   "description": "Arc framework core rewrite with improved event emission and type safety",