@arcote.tech/arc 0.3.6 → 0.4.1

package/dist/model/context-accessor.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Context Accessor — builds typed accessors from context elements without Proxy.
+ *
+ * Shared between query and mutation: iterates context elements,
+ * calls their queryContext() or mutateContext(), and wraps each method
+ * with an onCall handler.
+ *
+ * Two use cases:
+ * - Descriptor builder: onCall returns a ContextDescriptor (serializable)
+ * - Direct execution: onCall executes the method (React hooks, server calls)
+ */
+import type { ArcContextAny } from "../context/context";
+import type { ModelAdapters } from "./model-adapters";
+/**
+ * Serializable descriptor for a context method call.
+ * Works for both queries and mutations.
+ */
+export interface ContextDescriptor {
+    element: string;
+    method: string;
+    args: any[];
+}
+/**
+ * Callback invoked when an accessor method is called.
+ * Receives the descriptor and a thunk to execute the original method.
+ */
+export type OnAccessorCall<R> = (descriptor: ContextDescriptor, execute: () => any) => R;
+/**
+ * Build a typed accessor object from context elements.
+ *
+ * Iterates all elements, calls `contextMethod` (e.g., "queryContext" or "mutateContext")
+ * on each, and wraps every returned method with the `onCall` handler.
+ *
+ * Result shape: `{ elementName: { methodName: (...args) => onCall(...) } }`
+ *
+ * @param context - The ArcContext containing elements
+ * @param adapters - ModelAdapters passed to queryContext/mutateContext
+ * @param contextMethod - "queryContext" or "mutateContext"
+ * @param onCall - Handler called when a method is invoked
+ */
+export declare function buildContextAccessor<C extends ArcContextAny, R>(context: C, adapters: ModelAdapters, contextMethod: "queryContext" | "mutateContext", onCall: OnAccessorCall<R>): Record<string, Record<string, (...args: any[]) => R>>;
+/**
+ * Execute a context descriptor against a model.
+ *
+ * @param descriptor - The serialized descriptor
+ * @param context - ArcContext containing elements
+ * @param adapters - ModelAdapters for queryContext/mutateContext
+ * @param contextMethod - "queryContext" or "mutateContext"
+ */
+export declare function executeDescriptor(descriptor: ContextDescriptor, context: ArcContextAny, adapters: ModelAdapters, contextMethod: "queryContext" | "mutateContext"): any;
+//# sourceMappingURL=context-accessor.d.ts.map

package/dist/model/index.d.ts

@@ -1,4 +1,8 @@
 export * from "./model";
+export * from "./model-adapters";
+export * from "./model-like";
+export * from "./scoped-model";
+export * from "./context-accessor";
 export * from "./mutation-executor";
 export * from "./live-query";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1,32 +1,10 @@
 import type { ArcContextAny } from "../../context/context";
 import type { Simplify } from "../../utils";
-import type { Model } from "../model";
+/**
+ * QueryContext type — maps context element names to their queryContext return types.
+ * Used for typing useQuery() accessor.
+ */
 export type QueryContext<C extends ArcContextAny> = Simplify<{
     [Element in C["elements"][number] as Element["queryContext"] extends (...args: any[]) => infer Return ? Element["name"] : never]: Element["queryContext"] extends (...args: any[]) => infer Return ? Return : never;
 }>;
-/**
- * Live Query Result
- */
-export type LiveQueryResult<T> = {
-    result: T;
-    unsubscribe: () => void;
-};
-/**
- * Live Query
- *
- * Creates a live query that watches views and calls a callback when data changes.
- * Uses view's queryContext directly (applies protectBy restrictions).
- * Uses dataStorage.observeQueries() for reactivity when available.
- * Falls back to streaming mode (SSE) when no local storage.
- *
- * @example
- * ```typescript
- * const { result, unsubscribe } = liveQuery(
- *   model,
- *   (q) => q.tasks.find({ projectId: "123" }),
- *   (data) => console.log("Tasks updated:", data)
- * );
- * ```
- */
-export declare function liveQuery<C extends ArcContextAny, TResult>(model: Model<C>, queryFn: (q: QueryContext<C>) => Promise<TResult>, callback: (data: TResult) => void): LiveQueryResult<TResult>;
 //# sourceMappingURL=live-query.d.ts.map

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

@@ -14,5 +14,10 @@ export type ModelAdapters = {
     queryWire?: QueryWire;
     /** Streaming mode cache - used when no local dataStorage */
     streamingCache?: StreamingQueryCache;
+    /** Scope reference — set by ScopedModel for auth injection into wire calls */
+    scope?: {
+        readonly scopeName: string;
+        getToken(): string | null;
+    };
 };
 //# sourceMappingURL=model-adapters.d.ts.map

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

@@ -0,0 +1,9 @@
+import type { ArcEnvironment } from "../context-element/context-element";
+import type { ArcContextAny } from "../context/context";
+import type { ModelAdapters } from "./model-adapters";
+export interface ModelLike<C extends ArcContextAny> {
+    readonly context: C;
+    getAdapters(): ModelAdapters;
+    getEnvironment(): ArcEnvironment;
+}
+//# sourceMappingURL=model-like.d.ts.map

package/dist/model/model.d.ts

@@ -1,11 +1,14 @@
 import type { ArcEnvironment } from "../context-element/context-element";
 import type { ArcContextAny } from "../context/context";
 import type { ModelAdapters } from "./model-adapters";
-export declare class Model<Context extends ArcContextAny> {
+import type { ModelLike } from "./model-like";
+import { ScopedModel } from "./scoped-model";
+export declare class Model<Context extends ArcContextAny> implements ModelLike<Context> {
     readonly context: Context;
     private adapters;
     private environment;
     private initialized;
+    private scopes;
     constructor(context: Context, options: {
         adapters: ModelAdapters;
         environment: ArcEnvironment;
@@ -17,5 +20,11 @@ export declare class Model<Context extends ArcContextAny> {
     init(): Promise<void>;
     getAdapters(): ModelAdapters;
     getEnvironment(): ArcEnvironment;
+    /**
+     * Get or create a named scope.
+     * Scopes are cached — same name returns the same instance.
+     * For per-request isolation (server), use `new ScopedModel(model, name)` directly.
+     */
+    scope(name: string): ScopedModel<Context>;
 }
 //# sourceMappingURL=model.d.ts.map

package/dist/model/mutation-executor/mutation-executor.d.ts

@@ -1,6 +1,6 @@
 import type { ArcContextAny } from "../../context/context";
 import type { Simplify } from "../../utils";
-import type { Model } from "../model";
+import type { ModelLike } from "../model-like";
 /**
  * Mutation Executor Type
  *
@@ -25,5 +25,5 @@ export type MutationExecutor<C extends ArcContextAny> = Simplify<{
  * await mutations.createTask({ title: "New task" });
  * ```
  */
-export declare function mutationExecutor<C extends ArcContextAny>(model: Model<C>): MutationExecutor<C>;
+export declare function mutationExecutor<C extends ArcContextAny>(model: ModelLike<C>): MutationExecutor<C>;
 //# sourceMappingURL=mutation-executor.d.ts.map

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

@@ -0,0 +1,66 @@
+import { type DecodedToken } from "../adapters/auth-adapter";
+import type { ArcEnvironment } from "../context-element/context-element";
+import type { ArcContextAny } from "../context/context";
+import { type ContextDescriptor } from "./context-accessor";
+import type { ModelAdapters } from "./model-adapters";
+import type { ModelLike } from "./model-like";
+/**
+ * ScopedModel — a lightweight wrapper over a parent Model with scope-specific auth.
+ *
+ * Provides its own AuthAdapter (in-memory), explicit wire methods with auto-injected
+ * scope + token (no Proxy), and typed query/command accessors.
+ *
+ * For long-lived named scopes (client): use `model.scope("workspace")` (cached).
+ * For per-request isolation (server): use `new ScopedModel(model, name)` directly.
+ */
+export declare class ScopedModel<Context extends ArcContextAny> implements ModelLike<Context> {
+    readonly context: Context;
+    readonly scopeName: string;
+    private readonly parent;
+    private readonly authAdapter;
+    private readonly scopedAdapters;
+    private tokenListeners;
+    constructor(parent: ModelLike<Context>, scopeName: string);
+    setToken(token: string | null): void;
+    getToken(): string | null;
+    getDecoded(): DecodedToken | null;
+    getParams(): Record<string, any> | null;
+    isAuthenticated(): boolean;
+    onTokenChange(listener: () => void): () => void;
+    getAdapters(): ModelAdapters;
+    getEnvironment(): ArcEnvironment;
+    private getAuth;
+    /**
+     * Execute a command via CommandWire with auto-injected scope + token.
+     */
+    executeCommand(name: string, params: any): Promise<any>;
+    /**
+     * Execute a remote query via QueryWire with auto-injected scope + token.
+     */
+    remoteQuery(viewName: string, options?: any): Promise<any[]>;
+    /**
+     * Subscribe to a server-side query via EventWire with auto-injected scope.
+     */
+    subscribeQuery(descriptor: ContextDescriptor, callback: (data: any[]) => void): string;
+    /**
+     * Query descriptor builder. Returns serializable descriptors.
+     *
+     * Usage: `scope.query.userAccount.find({ where: { _id: "abc" } })`
+     */
+    get query(): Record<string, Record<string, (...args: any[]) => ContextDescriptor>>;
+    /**
+     * Command descriptor builder. Returns serializable descriptors.
+     *
+     * Usage: `scope.command.userAccount.createUser({ name: "Jan" })`
+     */
+    get command(): Record<string, Record<string, (...args: any[]) => ContextDescriptor>>;
+    /**
+     * Execute a query descriptor.
+     */
+    callQuery(descriptor: ContextDescriptor): Promise<any>;
+    /**
+     * Execute a command descriptor.
+     */
+    callCommand(descriptor: ContextDescriptor): Promise<any>;
+}
+//# sourceMappingURL=scoped-model.d.ts.map

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

@@ -0,0 +1,23 @@
+/**
+ * Scoped Wire Proxy - Creates proxy wrappers that auto-inject scope + token
+ *
+ * The proxy pattern means internal core code (Model, mutationExecutor, liveQuery)
+ * doesn't need signature changes — the proxy handles auth at the boundary.
+ */
+import type { CommandWire } from "../adapters/command-wire";
+import type { EventWire } from "../adapters/event-wire";
+import type { QueryWire } from "../adapters/query-wire";
+/**
+ * Create a proxy around CommandWire that auto-injects scope + token
+ */
+export declare function scopedCommandWire(wire: CommandWire, scope: string, getToken: () => string | null): CommandWire;
+/**
+ * Create a proxy around QueryWire that auto-injects scope + token
+ */
+export declare function scopedQueryWire(wire: QueryWire, scope: string, getToken: () => string | null): QueryWire;
+/**
+ * Create a proxy around EventWire that auto-injects scope into subscriptions.
+ * subscribeView(viewName, options, callback, scope?) — scope is the 4th arg.
+ */
+export declare function scopedEventWire(wire: EventWire, scope: string): EventWire;
+//# sourceMappingURL=scoped-wire-proxy.d.ts.map

package/dist/streaming/index.d.ts

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

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

@@ -1,27 +1,25 @@
 /**
  * StreamingLiveQuery - Live query implementation for streaming mode
  *
- * Uses SSE stream to get initial data and updates from server.
- * Uses StreamingQueryCache for local state and reactivity.
- * Deduplicates SSE streams - multiple queries on same view share one stream.
- * Static views are handled directly without SSE.
+ * Uses WebSocket view subscriptions for both initial data and live updates.
+ * Server runs liveQuery on view tables and pushes results via WS.
+ * Static views are handled directly without network.
  */
-import type { QueryWire } from "../adapters/query-wire";
+import type { EventWire } from "../adapters/event-wire";
 import type { ArcContextAny } from "../context/context";
 import type { LiveQueryResult, QueryContext } from "../model/live-query/live-query";
-import type { Model } from "../model/model";
+import type { ModelLike } from "../model/model-like";
 import type { StreamingQueryCache } from "./streaming-query-cache";
 export interface StreamingLiveQueryOptions {
-    queryWire: QueryWire;
     cache: StreamingQueryCache;
-    authToken?: string | null;
+    eventWire: EventWire;
 }
 /**
  * Create a streaming live query
  *
- * Opens SSE stream to server, populates cache, and reacts to changes.
- * Reuses existing streams for the same view (deduplication via cache).
- * Static views return data directly without SSE.
+ * Subscribes to server-side view queries via WebSocket.
+ * Server runs liveQuery and pushes view-data messages on change.
+ * Static views return data directly without network.
  */
-export declare function streamingLiveQuery<C extends ArcContextAny, TResult>(model: Model<C>, queryFn: (q: QueryContext<C>) => Promise<TResult>, callback: (data: TResult) => void, options: StreamingLiveQueryOptions): LiveQueryResult<TResult>;
+export declare function streamingLiveQuery<C extends ArcContextAny, TResult>(model: ModelLike<C>, queryFn: (q: QueryContext<C>) => Promise<TResult>, callback: (data: TResult) => void, options: StreamingLiveQueryOptions): LiveQueryResult<TResult>;
 //# sourceMappingURL=streaming-live-query.d.ts.map

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

@@ -11,17 +11,24 @@
  * - Receives updates from SSE stream
  * - Deduplicates SSE streams (one stream per view)
  */
+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";
-export type CacheChangeListener = () => void;
+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;
 }
 /**
  * StreamingQueryCache - Main cache class
@@ -30,6 +37,8 @@ export declare class StreamingQueryCache {
     private stores;
     private views;
     private activeStreams;
+    private pendingUnsubscribes;
+    private static UNSUBSCRIBE_DELAY_MS;
     /**
      * Register views that this cache will handle
      */
@@ -59,15 +68,27 @@ export declare class StreamingQueryCache {
         wasReused: boolean;
     };
     /**
-     * Unregister from a stream (decrement ref count, close if zero)
+     * 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;
     /**
-     * Set initial data for a view (from SSE stream)
+     * Subscribe to a query via WebSocket with deduplication.
+     * Multiple callers share a single WS subscription per descriptor key.
+     * Returns unsubscribe function that decrements refcount.
+     */
+    subscribeQuery(descriptor: {
+        element: string;
+        method: string;
+        args: any[];
+    }, eventWire: EventWire, scope?: string): () => void;
+    /**
+     * Set data for a view. Accepts array or single item (from queryMethod findOne).
      */
     setViewData<Item extends {
         _id: string;
-    }>(viewName: string, items: Item[]): void;
+    }>(viewName: string, data: Item[] | Item | undefined | null): void;
     /**
      * Apply an event to update view state
      * Runs view handlers to update the cache

package/package.json

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