@arcote.tech/arc 0.1.12 → 0.3.0

package/dist/model/index.d.ts

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

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

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

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

@@ -0,0 +1,31 @@
+import type { ArcContextAny } from "../../context/context";
+import type { Simplify } from "../../utils";
+import type { Model } from "../model";
+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.
+ *
+ * @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/live-query/query-cache.d.ts

@@ -0,0 +1,60 @@
+import type { FindOptions, QueryListenerCallback } from "../../data-storage";
+/**
+ * Cache for query results with change resolution
+ * Stores results per store + serialized options
+ */
+export declare class QueryCache {
+    private cache;
+    private onChangeCallback;
+    /**
+     * Set callback to be called when any cached result changes
+     */
+    onChange(callback: () => void): void;
+    /**
+     * Get cache key from options
+     */
+    private getOptionsKey;
+    /**
+     * Get or create store cache
+     */
+    private getStoreCache;
+    /**
+     * Check if we have a cached result for this store + options
+     */
+    has(storeName: string, options: FindOptions<any>): boolean;
+    /**
+     * Get cached result for store + options
+     */
+    get<Item extends {
+        _id: string;
+    }>(storeName: string, options: FindOptions<Item>): Item[] | undefined;
+    /**
+     * Get or create listener for store + options
+     * Returns existing listener if already cached, or creates new one
+     */
+    getOrCreateListener<Item extends {
+        _id: string;
+    }>(storeName: string, options: FindOptions<Item>): QueryListenerCallback<Item>;
+    /**
+     * Update cached result after fetch
+     */
+    updateResult<Item extends {
+        _id: string;
+    }>(storeName: string, options: FindOptions<Item>, result: Item[]): void;
+    /**
+     * Apply change events to cached result
+     */
+    private applyChanges;
+    /**
+     * Get all listeners for unsubscribing
+     */
+    getAllListeners(): Array<{
+        storeName: string;
+        listener: QueryListenerCallback<any>;
+    }>;
+    /**
+     * Clear all cached data
+     */
+    clear(): void;
+}
+//# sourceMappingURL=query-cache.d.ts.map

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

@@ -0,0 +1,13 @@
+import type { AuthAdapter } from "../adapters/auth-adapter";
+import type { CommandWire } from "../adapters/command-wire";
+import type { EventPublisher } from "../adapters/event-publisher";
+import type { EventWire } from "../adapters/event-wire";
+import type { DataStorage } from "../data-storage";
+export type ModelAdapters = {
+    dataStorage?: DataStorage;
+    commandWire?: CommandWire;
+    eventPublisher?: EventPublisher;
+    eventWire?: EventWire;
+    authAdapter?: AuthAdapter;
+};
+//# sourceMappingURL=model-adapters.d.ts.map

package/dist/model/model.d.ts

@@ -1,80 +1,21 @@
-import { type ArcContextAny, type IArcQueryBuilder } from "../context";
-import type { ArcContextElementMethodReturnType } from "../context/context";
-import type { AuthContext } from "../context/element";
-import { type DataStorage } from "../data-storage";
-type UnaryFunction<T, R> = (input: T) => R;
-export declare abstract class ModelBase<C extends ArcContextAny> {
-    protected token: string | null;
-    /**
-     * Set the authentication token for API requests
-     */
-    setAuthToken(token: string | null): void;
-    abstract query<Q extends IArcQueryBuilder>(queryBuilderFn: UnaryFunction<ReturnType<C["queryBuilder"]>, Q>, authContext: AuthContext): Promise<ReturnType<Q["toQuery"]>["lastResult"]>;
-    abstract subscribe<Q extends IArcQueryBuilder>(queryBuilderFn: UnaryFunction<ReturnType<C["queryBuilder"]>, Q>, callback: (result: ReturnType<Q["toQuery"]>["lastResult"]) => void, authContext: AuthContext): {
-        result: ReturnType<Q["toQuery"]>["lastResult"];
-        unsubscribe: () => void;
-    };
-    abstract commands(authContext: AuthContext): ArcContextElementMethodReturnType<C["elements"], "commandClient">;
-    abstract routes(authContext: AuthContext): any;
-}
-export declare class Model<C extends ArcContextAny> extends ModelBase<C> {
-    private readonly context;
-    private readonly dataStorage?;
-    private readonly catchErrorCallback?;
-    private queryCache;
-    constructor(context: C, dataStorage?: DataStorage | undefined, catchErrorCallback?: ((error: any) => void) | undefined);
-    query<Q extends IArcQueryBuilder>(queryBuilderFn: UnaryFunction<ReturnType<C["queryBuilder"]>, Q>, authContext: AuthContext): Promise<ReturnType<Q["toQuery"]>["lastResult"]>;
-    subscribe<Q extends IArcQueryBuilder>(queryBuilderFn: UnaryFunction<ReturnType<C["queryBuilder"]>, Q>, callback: (result: ReturnType<Q["toQuery"]>["lastResult"]) => void, authContext: AuthContext): {
-        result: ReturnType<Q["toQuery"]>["lastResult"];
-        unsubscribe: () => void;
-    };
-    commands(authContext: AuthContext): ArcContextElementMethodReturnType<C["elements"], "commandClient">;
-    routes(authContext: AuthContext): any;
-    get $debug(): {};
-}
-export declare class RemoteModelClient<C extends ArcContextAny> extends ModelBase<C> {
-    private readonly context;
-    private readonly apiBaseUrl;
-    private readonly client;
-    private readonly catchErrorCallback;
-    private queryCache;
-    private inFlightRequests;
-    constructor(context: C, apiBaseUrl: string, client: string, catchErrorCallback: (error: any) => void);
-    /**
-     * Generate a cache key from query details
-     */
-    private generateCacheKey;
-    /**
-     * Execute the actual HTTP query request
-     */
-    private executeQuery;
-    /**
-     * Check if a schema contains blob or file elements
-     */
-    private schemaContainsBlobOrFile;
-    /**
-     * Recursively check object shape for blob/file elements
-     */
-    private checkShapeForBlobOrFile;
-    /**
-     * Check if an element is a blob or file element
-     */
-    private isBlobOrFileElement;
-    /**
-     * Convert an object to FormData, handling nested objects and blobs
-     */
-    private objectToFormData;
-    /**
-     * Get authorization headers for API requests
-     */
-    private getAuthHeaders;
-    query<Q extends IArcQueryBuilder>(queryBuilderFn: UnaryFunction<ReturnType<C["queryBuilder"]>, Q>, authContext: AuthContext): Promise<ReturnType<Q["toQuery"]>["lastResult"]>;
-    subscribe<Q extends IArcQueryBuilder>(queryBuilderFn: UnaryFunction<ReturnType<C["queryBuilder"]>, Q>, callback: (result: ReturnType<Q["toQuery"]>["lastResult"]) => void, authContext: AuthContext): {
-        result: ReturnType<Q["toQuery"]>["lastResult"];
-        unsubscribe: () => void;
-    };
-    commands(authContext: AuthContext): ArcContextElementMethodReturnType<C["elements"], "commandClient">;
-    routes(authContext: AuthContext): any;
+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> {
+    readonly context: Context;
+    private adapters;
+    private environment;
+    private initialized;
+    constructor(context: Context, options: {
+        adapters: ModelAdapters;
+        environment: ArcEnvironment;
+    });
+    /**
+     * Initialize all context elements
+     * Should be called after model creation
+     */
+    init(): Promise<void>;
+    getAdapters(): ModelAdapters;
+    getEnvironment(): ArcEnvironment;
 }
-export {};
 //# sourceMappingURL=model.d.ts.map

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

@@ -0,0 +1,2 @@
+export * from "./mutation-executor";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,29 @@
+import type { ArcContextAny } from "../../context/context";
+import type { Simplify } from "../../utils";
+import type { Model } from "../model";
+/**
+ * Mutation Executor Type
+ *
+ * Extracts all elements that have a mutateContext method and creates
+ * a typed object with methods for executing mutations (commands).
+ */
+export type MutationExecutor<C extends ArcContextAny> = Simplify<{
+    [Element in C["elements"][number] as Element["mutateContext"] extends (...args: any[]) => infer Return ? Element["name"] : never]: Element["mutateContext"] extends (...args: any[]) => infer Return ? Return : never;
+}>;
+/**
+ * Mutation Executor
+ *
+ * Creates a typed proxy object with methods for each command in the context.
+ * Each method executes the command with proper context and handles event emission.
+ *
+ * @example
+ * ```typescript
+ * const model = new Model(myContext);
+ * const mutations = mutationExecutor(model);
+ *
+ * // Type-safe command execution
+ * await mutations.createTask({ title: "New task" });
+ * ```
+ */
+export declare function mutationExecutor<C extends ArcContextAny>(model: Model<C>): MutationExecutor<C>;
+//# sourceMappingURL=mutation-executor.d.ts.map

package/dist/token/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Token - Security context abstraction for Arc Framework
+ *
+ * Tokens provide a unified way to handle authentication and authorization
+ * across all layers of the application:
+ *
+ * - React hooks (useCommands with token)
+ * - Commands (protectBy)
+ * - Views/Events (protectBy) - Protection rules defined here
+ * - DataStorage (secure)
+ * - Wire (JWT)
+ *
+ * @example
+ * ```typescript
+ * // Define a token
+ * const userToken = token("user", { userId: string() })
+ *   .secret(process.env.USER_SECRET)
+ *   .withRules({
+ *     'task:create': async () => true,
+ *   });
+ *
+ * // Define protection on view (not on token!)
+ * const tasks = view("tasks", taskId, taskSchema)
+ *   .protectBy(userToken, (params) => ({
+ *     read: { userId: params.userId },
+ *     write: { userId: params.userId },
+ *   }));
+ *
+ * // Create instance and use
+ * const instance = userToken.create({ userId: "user_123" });
+ * const jwt = instance.getJWT();
+ * const canCreate = await instance.canI('task:create');
+ * const securedStorage = secureDataStorage(dataStorage, instance, context);
+ * ```
+ */
+export { secureDataStorage, SecuredDataStorage, SecuredStoreState, } from "./secured-data-storage";
+export { ArcToken, token, type ArcTokenAny } from "./token";
+export { TokenCache, type TokenCacheOptions } from "./token-cache";
+export type { ArcTokenData, TokenParams, TokenRule, TokenRuleContext, TokenRules, } from "./token-data";
+export { TokenInstance, type TokenInstanceAny } from "./token-instance";
+//# sourceMappingURL=index.d.ts.map

package/dist/token/secured-data-storage.d.ts

@@ -0,0 +1,125 @@
+/**
+ * SecuredDataStorage - DataStorage wrapper with token-based security
+ *
+ * Wraps a DataStorage instance and automatically applies token-based
+ * WHERE conditions to all queries. Protection rules are defined on
+ * views/events via .protectBy(), not on the token itself.
+ *
+ * @example
+ * ```typescript
+ * // View defines its own protection
+ * const tasks = view("tasks", taskId, taskSchema)
+ *   .protectBy(userToken, (params) => ({
+ *     read: { userId: params.userId },
+ *     write: { userId: params.userId },
+ *   }));
+ *
+ * // SecuredDataStorage uses view's protection
+ * const securedStorage = new SecuredDataStorage(dataStorage, tokenInstance, context);
+ * const myTasks = await securedStorage.getStore("tasks").find({});
+ * ```
+ */
+import type { ArcContextAny } from "../context/context";
+import type { DataStorage } from "../data-storage/data-storage.abstract";
+import type { FindOptions } from "../data-storage/find-options";
+import type { StoreState } from "../data-storage/store-state.abstract";
+import type { TokenInstanceAny } from "./token-instance";
+/**
+ * Secured store state wrapper
+ * Applies token conditions to all queries based on view's protectBy config
+ */
+export declare class SecuredStoreState<Item extends {
+    _id: string;
+}> {
+    private readonly store;
+    private readonly tokenInstance;
+    private readonly storeName;
+    private readonly context?;
+    private readonly protection;
+    constructor(store: StoreState<Item>, tokenInstance: TokenInstanceAny, storeName: string, context?: ArcContextAny | undefined);
+    /**
+     * Get protection config from view's protectBy
+     */
+    private getProtectionFromContext;
+    /**
+     * Find items with token-based filtering
+     */
+    find(options?: FindOptions<Item>): Promise<Item[]>;
+    /**
+     * Set item with token-based write check
+     */
+    set(item: Item): Promise<void>;
+    /**
+     * Remove item with token-based write check
+     */
+    remove(id: string): Promise<void>;
+    /**
+     * Modify item with token-based write check
+     */
+    modify(id: string, data: Partial<Item>): Promise<{
+        from: Item | null;
+        to: Item | null;
+    }>;
+    /**
+     * Apply changes with token-based write check
+     */
+    applyChanges(changes: any[]): Promise<void>;
+    /**
+     * Fork the store (returns unsecured fork)
+     */
+    fork(): import("..").ForkedStoreState<Item>;
+    /**
+     * Apply token condition to find options
+     */
+    private applyTokenCondition;
+    /**
+     * Check if write is allowed
+     */
+    private canWrite;
+    /**
+     * Get write condition
+     */
+    private getWriteCondition;
+    /**
+     * Check if item matches a condition (simple implementation)
+     */
+    private itemMatchesCondition;
+}
+/**
+ * SecuredDataStorage - DataStorage wrapper with token-based security
+ */
+export declare class SecuredDataStorage {
+    private readonly dataStorage;
+    private readonly tokenInstance;
+    private readonly context?;
+    private readonly storeCache;
+    constructor(dataStorage: DataStorage, tokenInstance: TokenInstanceAny, context?: ArcContextAny | undefined);
+    /**
+     * Get a secured store by name
+     */
+    getStore<Item extends {
+        _id: string;
+    }>(storeName: string): SecuredStoreState<Item>;
+    /**
+     * Get the underlying unsecured DataStorage
+     * Use with caution!
+     */
+    getUnsecuredStorage(): DataStorage;
+    /**
+     * Get the token instance used for security
+     */
+    getTokenInstance(): TokenInstanceAny;
+    /**
+     * Fork the data storage (returns unsecured fork)
+     */
+    fork(): import("..").ForkedDataStorage;
+}
+/**
+ * Create a SecuredDataStorage from DataStorage and token instance
+ *
+ * @param dataStorage - The DataStorage to secure
+ * @param tokenInstance - Token instance for security context
+ * @param context - Optional context to get view protections from
+ */
+export declare function secureDataStorage(dataStorage: DataStorage, tokenInstance: TokenInstanceAny, context?: ArcContextAny): SecuredDataStorage;
+//# sourceMappingURL=secured-data-storage.d.ts.map

package/dist/token/token-cache.d.ts

@@ -0,0 +1,100 @@
+/**
+ * TokenCache - Server-side caching for resolved tokens
+ *
+ * Caches token instances and permission results to avoid
+ * repeated database queries for the same token.
+ *
+ * @example
+ * ```typescript
+ * const cache = new TokenCache({ ttl: 60000 }); // 1 minute TTL
+ *
+ * // Get or create cached instance
+ * const instance = await cache.getOrCreate(jwt, () => token.parseJWT(jwt));
+ *
+ * // Cache permission results
+ * const canEdit = await cache.getPermission(instance, 'form:edit', () =>
+ *   instance.canI('form:edit')
+ * );
+ * ```
+ */
+import type { TokenInstanceAny } from "./token-instance";
+export interface TokenCacheOptions {
+    /**
+     * Time-to-live in milliseconds
+     * Default: 5 minutes
+     */
+    ttl?: number;
+    /**
+     * Maximum number of cached entries
+     * Default: 1000
+     */
+    maxSize?: number;
+}
+export declare class TokenCache {
+    private readonly instanceCache;
+    private readonly permissionCache;
+    private readonly ttl;
+    private readonly maxSize;
+    constructor(options?: TokenCacheOptions);
+    /**
+     * Get cached token instance or create new one
+     *
+     * @param jwt - JWT string as cache key
+     * @param factory - Function to create instance if not cached
+     */
+    getOrCreate<T extends TokenInstanceAny>(jwt: string, factory: () => T | null | Promise<T | null>): Promise<T | null>;
+    /**
+     * Get cached permission result or compute it
+     *
+     * @param instance - Token instance
+     * @param permission - Permission name
+     * @param factory - Function to compute permission if not cached
+     */
+    getPermission(instance: TokenInstanceAny, permission: string, factory: () => Promise<boolean>): Promise<boolean>;
+    /**
+     * Cache a token instance
+     */
+    private setInstance;
+    /**
+     * Cache a permission result
+     */
+    private setPermission;
+    /**
+     * Generate cache key for permission
+     */
+    private getPermissionKey;
+    /**
+     * Ensure cache doesn't exceed max size
+     */
+    private ensureCapacity;
+    /**
+     * Invalidate all cached data for a specific token instance
+     *
+     * @param instance - Token instance to invalidate
+     */
+    invalidateInstance(instance: TokenInstanceAny): void;
+    /**
+     * Invalidate a specific JWT
+     *
+     * @param jwt - JWT string to invalidate
+     */
+    invalidateJWT(jwt: string): void;
+    /**
+     * Clear all cached data
+     */
+    clear(): void;
+    /**
+     * Remove expired entries
+     */
+    cleanup(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        instanceCount: number;
+        permissionCount: number;
+        maxSize: number;
+        ttl: number;
+    };
+}
+//# sourceMappingURL=token-cache.d.ts.map

package/dist/token/token-data.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Token Data Types
+ *
+ * Type definitions for the Token security abstraction
+ */
+import type { ArcContextElement } from "../context-element/context-element";
+import type { ArcObject, ArcRawShape } from "../elements/object";
+/**
+ * Token parameters schema - defines what data the token carries
+ */
+export type TokenParams = Record<string, any>;
+/**
+ * Context provided to rule functions
+ * Contains query elements for checking permissions
+ */
+export type TokenRuleContext<QueryElements extends ArcContextElement<any>[]> = {
+    [K in QueryElements[number] as K["name"]]: K["queryContext"] extends (...args: any) => infer R ? R : never;
+};
+/**
+ * Rule function signature
+ * Async function that checks if permission is granted
+ */
+export type TokenRule<Params extends TokenParams, QueryElements extends ArcContextElement<any>[]> = (ctx: TokenRuleContext<QueryElements>, params: Params) => Promise<boolean>;
+/**
+ * Rules map - permission name to rule function
+ */
+export type TokenRules<Params extends TokenParams, QueryElements extends ArcContextElement<any>[]> = Record<string, TokenRule<Params, QueryElements>>;
+/**
+ * Token data structure - internal configuration
+ */
+export type ArcTokenData<Name extends string = string, ParamsShape extends ArcRawShape = ArcRawShape, QueryElements extends ArcContextElement<any>[] = ArcContextElement<any>[], Rules extends TokenRules<any, QueryElements> = TokenRules<any, QueryElements>> = {
+    name: Name;
+    paramsSchema: ArcObject<ParamsShape>;
+    secret?: string;
+    queryElements: QueryElements;
+    rules: Rules;
+};
+//# sourceMappingURL=token-data.d.ts.map

package/dist/token/token-instance.d.ts

@@ -0,0 +1,71 @@
+/**
+ * TokenInstance - A concrete instance of a token with actual parameter values
+ *
+ * Created from:
+ * - token.create({ userId: "123" })
+ * - token.parseJWT(jwtString)
+ *
+ * Used for:
+ * - Permission checks: instance.canI('form:edit')
+ * - JWT generation: instance.getJWT()
+ */
+import type { ModelAdapters } from "../model/model-adapters";
+import type { TokenParams } from "./token-data";
+/**
+ * Interface for token definition (avoids circular import)
+ */
+export interface ITokenDefinition {
+    name: string;
+    checkPermission(permission: string, params: any, adapters?: ModelAdapters): Promise<boolean>;
+    generateJWT(params: any, expiresIn?: number): string;
+}
+export declare class TokenInstance<Params extends TokenParams, RuleNames extends string = string> {
+    private readonly token;
+    readonly params: Params;
+    private readonly adapters?;
+    constructor(token: ITokenDefinition, params: Params, adapters?: ModelAdapters | undefined);
+    /**
+     * Check if this token instance has a specific permission
+     *
+     * @param permission - Permission name (e.g., 'form:edit')
+     * @returns Promise<boolean> - Whether permission is granted
+     *
+     * @example
+     * ```typescript
+     * if (await tokenInstance.canI('form:edit')) {
+     *   // User can edit form
+     * }
+     * ```
+     */
+    canI(permission: RuleNames): Promise<boolean>;
+    /**
+     * Generate JWT string from this token instance
+     *
+     * @returns JWT string containing token name and params
+     *
+     * @example
+     * ```typescript
+     * const jwt = tokenInstance.getJWT();
+     * // Use in Authorization header
+     * ```
+     */
+    getJWT(): string;
+    /**
+     * Get the token definition this instance was created from
+     */
+    getTokenDefinition(): ITokenDefinition;
+    /**
+     * Get token name
+     */
+    get name(): string;
+    /**
+     * Create a new instance with updated adapters
+     * Used when adapters become available later
+     */
+    withAdapters(adapters: ModelAdapters): TokenInstance<Params, RuleNames>;
+}
+/**
+ * Type helper for any token instance
+ */
+export type TokenInstanceAny = TokenInstance<any, any>;
+//# sourceMappingURL=token-instance.d.ts.map