@arcote.tech/arc 0.1.11 → 0.3.0

package/dist/adapters/auth-adapter.d.ts

@@ -0,0 +1,47 @@
+/**
+ * AuthAdapter - Manages authentication token for the model
+ *
+ * Stores the current JWT token and provides decoded params.
+ * On client: decodes token without signature verification
+ * On server: token is verified before being set
+ */
+export interface DecodedToken {
+    tokenName: string;
+    params: Record<string, any>;
+    iat?: number;
+    exp?: number;
+}
+export declare class AuthAdapter {
+    private token;
+    private decoded;
+    /**
+     * Set the JWT token
+     * Decodes the payload (without signature verification on client)
+     */
+    setToken(token: string | null): void;
+    /**
+     * Get the raw JWT token string
+     */
+    getToken(): string | null;
+    /**
+     * Get decoded token data
+     */
+    getDecoded(): DecodedToken | null;
+    /**
+     * Get token params (e.g., { userId, projectId })
+     */
+    getParams(): Record<string, any> | null;
+    /**
+     * Get token name (e.g., "user")
+     */
+    getTokenName(): string | null;
+    /**
+     * Check if token is set and valid
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Check if token is expired
+     */
+    isExpired(): boolean;
+}
+//# sourceMappingURL=auth-adapter.d.ts.map

package/dist/adapters/command-wire.d.ts

@@ -0,0 +1,28 @@
+/**
+ * CommandWire - Wire adapter specialized for command execution
+ *
+ * Extends Wire to provide command-specific functionality:
+ * - Execute commands remotely on the server
+ * - Handle command request/response serialization
+ */
+import { Wire } from "./wire";
+export declare class CommandWire extends Wire {
+    constructor(baseUrl: string);
+    /**
+     * Execute a command on the remote server
+     *
+     * @param name - Command name
+     * @param params - Command parameters
+     * @returns Command result from server
+     */
+    executeCommand(name: string, params: any): Promise<any>;
+    /**
+     * Register a command handler on the server side
+     * Called during init() for server environment
+     *
+     * @param name - Command name
+     * @param handler - Handler function to execute command
+     */
+    registerCommandHandler?(name: string, handler: (params: any) => Promise<any>): void;
+}
+//# sourceMappingURL=command-wire.d.ts.map

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

@@ -0,0 +1,106 @@
+/**
+ * EventPublisher - Adapter for publishing and synchronizing events
+ *
+ * Responsibilities:
+ * 1. Apply events to local views (via dataStorage)
+ * 2. Store events locally with sync status
+ * 3. Provide API for synchronization (implementation done elsewhere)
+ *
+ * All events are stored in shared tables:
+ * - events - single table for ALL events (distinguished by `type` field)
+ * - event_tags - tags with FK to events
+ * - event_sync_status - sync tracking (separate from events)
+ */
+import type { ArcEventAny } from "../context-element/event";
+import type { ArcEventInstance } from "../context-element/event/instance";
+import type { ArcViewAny } from "../context-element/view/view";
+import type { DataStorage } from "../data-storage";
+/** Shared table names for all events */
+export declare const EVENT_TABLES: {
+    readonly events: "events";
+    readonly tags: "event_tags";
+    readonly syncStatus: "event_sync_status";
+};
+/** Stored event record in the events table */
+export interface StoredEvent {
+    _id: string;
+    type: string;
+    payload: string;
+    createdAt: string;
+}
+/** Event tag record in the event_tags table */
+export interface StoredEventTag {
+    _id: string;
+    eventId: string;
+    tagKey: string;
+    tagValue: string;
+}
+/** Sync status record in the event_sync_status table */
+export interface StoredEventSyncStatus {
+    _id: string;
+    eventId: string;
+    synced: boolean;
+    timestamp: number;
+    retryCount: number;
+}
+/** Combined event with sync status for API consumers */
+export interface EventWithSyncStatus {
+    event: StoredEvent;
+    syncStatus: StoredEventSyncStatus;
+    tags: StoredEventTag[];
+}
+export interface EventPublisher {
+    /**
+     * Publish an event locally and mark for sync
+     *
+     * @param event - Event instance to publish
+     */
+    publish(event: ArcEventInstance<ArcEventAny>): Promise<void>;
+    /**
+     * Mark events as synced after successful server sync
+     *
+     * @param eventIds - Array of event IDs that were synced
+     */
+    markSynced(eventIds: string[]): Promise<void>;
+    /**
+     * Get all unsynced events, optionally filtered by event type
+     *
+     * @param eventType - Optional event type name to filter by
+     * @returns Array of unsynced events with their sync status
+     */
+    getUnsyncedEvents(eventType?: string): Promise<EventWithSyncStatus[]>;
+    /**
+     * Register views that should be updated when events are published
+     *
+     * @param views - Array of views to register
+     */
+    registerViews(views: ArcViewAny[]): void;
+}
+/**
+ * Local EventPublisher implementation
+ * Stores all events in shared tables, distinguished by `type` field
+ */
+export declare class LocalEventPublisher implements EventPublisher {
+    private readonly dataStorage;
+    private views;
+    private syncCallback?;
+    constructor(dataStorage: DataStorage);
+    /**
+     * Set a callback to be called after each event is published
+     * Used for syncing events to the host
+     */
+    onPublish(callback: (event: ArcEventInstance<ArcEventAny>) => void): void;
+    /**
+     * Register views that should be updated when events are published
+     */
+    registerViews(views: ArcViewAny[]): void;
+    publish(event: ArcEventInstance<ArcEventAny>): Promise<void>;
+    markSynced(eventIds: string[]): Promise<void>;
+    getUnsyncedEvents(eventType?: string): Promise<EventWithSyncStatus[]>;
+    /**
+     * Collect view changes without committing them
+     * Returns changes that can be batched with other changes
+     */
+    private collectViewChanges;
+}
+//# sourceMappingURL=event-publisher.d.ts.map

package/dist/adapters/event-wire.d.ts

@@ -0,0 +1,79 @@
+/**
+ * EventWire - WebSocket adapter for bidirectional event sync
+ *
+ * Connects to the host via WebSocket and:
+ * - Sends locally created events to the host
+ * - Receives events from the host (from other clients)
+ * - Handles reconnection and sync state
+ */
+export interface SyncableEvent {
+    localId: string;
+    type: string;
+    payload: any;
+    createdAt: string;
+}
+export interface ReceivedEvent {
+    localId: string;
+    hostId: string;
+    type: string;
+    payload: any;
+    createdAt: string;
+    clientId: string;
+}
+type EventWireState = "disconnected" | "connecting" | "connected";
+export declare class EventWire {
+    private readonly baseUrl;
+    private ws;
+    private state;
+    private token;
+    private lastHostEventId;
+    private pendingEvents;
+    private onEventCallback?;
+    private onSyncedCallback?;
+    private reconnectTimeout?;
+    private syncRequested;
+    constructor(baseUrl: string);
+    /**
+     * Set authentication token
+     */
+    setAuthToken(token: string | null): void;
+    /**
+     * Set the last synced host event ID
+     * Used to restore sync state after page refresh
+     */
+    setLastHostEventId(id: string | null): void;
+    /**
+     * Get the last synced host event ID
+     */
+    getLastHostEventId(): string | null;
+    /**
+     * Connect to the host WebSocket
+     */
+    connect(): void;
+    /**
+     * Disconnect from the host
+     */
+    disconnect(): void;
+    /**
+     * Send events to the host
+     */
+    syncEvents(events: SyncableEvent[]): void;
+    /**
+     * Set callback for receiving events from host
+     */
+    onEvent(callback: (event: ReceivedEvent) => void): void;
+    /**
+     * Set callback for when events are confirmed synced
+     */
+    onSynced(callback: (localIds: string[]) => void): void;
+    /**
+     * Get current connection state
+     */
+    getState(): EventWireState;
+    private handleMessage;
+    private requestSync;
+    private flushPendingEvents;
+    private scheduleReconnect;
+}
+export {};
+//# sourceMappingURL=event-wire.d.ts.map

package/dist/adapters/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Adapters - External dependencies for Arc Framework
+ *
+ * Adapters provide pluggable implementations for:
+ * - Wire: Client-server communication
+ * - CommandWire: Command execution over network
+ * - EventPublisher: Event persistence and synchronization
+ * - DataStorage: Data persistence (defined elsewhere)
+ */
+export { AuthAdapter } from "./auth-adapter";
+export type { DecodedToken } from "./auth-adapter";
+export { CommandWire } from "./command-wire";
+export { EventWire } from "./event-wire";
+export type { ReceivedEvent, SyncableEvent } from "./event-wire";
+export { Wire } from "./wire";
+export { EVENT_TABLES, LocalEventPublisher } from "./event-publisher";
+export type { EventPublisher, EventWithSyncStatus, StoredEvent, StoredEventSyncStatus, StoredEventTag, } from "./event-publisher";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/wire.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Wire - Base abstraction for client-server communication
+ *
+ * Handles JWT token management and provides fetch abstraction
+ * for making authenticated requests to the server.
+ */
+export declare class Wire {
+    private readonly baseUrl;
+    private token;
+    constructor(baseUrl: string);
+    /**
+     * Set authentication token for requests
+     */
+    setAuthToken(token: string | null): void;
+    /**
+     * Make authenticated fetch request to server
+     */
+    fetch(endpoint: string, options?: RequestInit): Promise<Response>;
+}
+//# sourceMappingURL=wire.d.ts.map

package/dist/context/context.d.ts

@@ -1,55 +1,52 @@
-import type { DataStorage } from "../data-storage";
-import type { objectUtil } from "../utils";
-import type { CommandContext } from "./commands";
-import type { ArcContextElement, ArcContextElementAny, AuthContext, EventListener, PublishEventFunction } from "./element";
-import type { QueryBuilderContext } from "./query-builder-context";
-type Filter<T extends any[], Method extends keyof T[number]> = T extends [
-    infer First,
-    ...infer Rest
-] ? First[Method] extends (...args: any) => any ? [First, ...Filter<Rest, Method>] : Filter<Rest, Method> : [];
-type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
-export type ArcContextElementMethodReturnType<Elements extends ArcContextElementAny[], Method extends keyof Elements[number]> = UnionToIntersection<{
-    [Element in Filter<Elements, Method>[number] as number]: {
-        [ElementName in Element["name"]]: Element[Method] extends (...args: any) => any ? ReturnType<Element[Method]> : undefined;
-    };
-}[number]>;
-export type ArcCommandContext<E extends ArcContextElementAny[]> = ArcContextElementMethodReturnType<E, "commandContext"> & {
-    $auth: AuthContext;
-} & {
-    get: <ArcElement extends ArcContextElementAny>(element: ArcElement) => ArcElement["commandContext"] extends infer CommandContext ? CommandContext extends (...args: any) => any ? ReturnType<CommandContext> : never : never;
-};
-export type RemoveFalseAndResolvedPromiseFromArray<T extends any[]> = T extends [infer First, ...infer Rest] ? First extends false ? RemoveFalseAndResolvedPromiseFromArray<Rest> : First extends Promise<{
-    default: infer Inner;
-}> ? RemoveFalseAndResolvedPromiseFromArray<[Inner, ...Rest]> : [First, ...RemoveFalseAndResolvedPromiseFromArray<Rest>] : [];
-export type FindElementByName<E extends ArcContextElementAny[], Name extends string> = E extends [
-    infer First extends ArcContextElementAny,
-    ...infer Rest extends ArcContextElementAny[]
-] ? First["name"] extends Name ? First : FindElementByName<Rest, Name> : never;
-export declare class ArcContext<const E extends ArcContextElementAny[]> {
-    readonly elements: E;
-    private elementsSet;
-    constructor(elements: E);
-    get<Name extends E[number]["name"]>(name: Name): FindElementByName<E, Name>;
-    getSyncListeners(eventType: string, authContext: AuthContext): EventListener<any>[];
-    getAsyncListeners(eventType: string, authContext: AuthContext): EventListener<any>[];
-    pipe<const NewElements extends (ArcContextElementAny | false | Promise<{
-        default: ArcContextElementAny;
-    }>)[]>(newElements: NewElements): ArcContext<[
-        ...E,
-        ...RemoveFalseAndResolvedPromiseFromArray<NewElements>
-    ]>;
-    queryBuilder(queryContext: QueryBuilderContext, authContext: AuthContext): ArcContextElementMethodReturnType<E, "queryBuilder">;
-    commandContext(dataStorage: DataStorage, publishEvent: PublishEventFunction, authContext: AuthContext): ArcCommandContext<E>;
+import type { ArcContextElement, ArcContextElementAny } from "../context-element/context-element";
+/**
+ * Arc Context
+ *
+ * A collection of context elements (commands, events, views, listeners).
+ * Provides a simple container for organizing related elements.
+ */
+export declare class ArcContext<const Elements extends ArcContextElement<any>[]> {
+    readonly elements: Elements;
+    readonly elementMap: Map<string, Elements[number]>;
+    constructor(elements: Elements);
+    /**
+     * Get an element by name
+     *
+     * @param name - The name of the element to retrieve
+     * @returns The element if found, undefined otherwise
+     */
+    get(name: string): Elements[number] | undefined;
 }
-export type ArcContextAny = ArcContext<ArcContextElementAny[]>;
-export type ElementEvents<Element extends ArcContextElementAny> = Element extends ArcContextElement<any> ? Element["$event"] : never;
-export type ContextEvents<Context extends ArcContextAny> = {
-    [Element in Context["elements"][number] as Element["name"]]: objectUtil.simplify<{
-        element: Element["name"];
-    } & ElementEvents<Element>>;
-}[Context["elements"][number]["name"]];
-export type Listener<Context extends ArcContextAny> = (event: ContextEvents<Context>, context: CommandContext<Context>) => Promise<void> | void;
-export declare function context<const Elements extends ArcContextElementAny[]>(elements: Elements): ArcContext<Elements>;
+/**
+ * Create a new context from an array of elements
+ *
+ * @param elements - Array of context elements (commands, events, views, listeners)
+ * @returns New context instance
+ *
+ * @example
+ * ```typescript
+ * const myContext = context([
+ *   myCommand,
+ *   myEvent,
+ *   myView,
+ * ]);
+ * ```
+ */
+export declare function context<const Elements extends ArcContextElement<any>[]>(elements: Elements): ArcContext<Elements>;
+/**
+ * Merge multiple contexts into one
+ *
+ * @param contexts - Contexts to merge
+ * @returns New context with all elements from all contexts
+ *
+ * @example
+ * ```typescript
+ * const mergedContext = contextMerge(authContext, taskContext, chatContext);
+ * ```
+ */
 export declare function contextMerge<const Contexts extends ArcContextAny[]>(...contexts: Contexts): ArcContext<Contexts[number]["elements"]>;
-export {};
+/**
+ * Type alias for any context (used in collections)
+ */
+export type ArcContextAny = ArcContext<ArcContextElementAny[]>;
 //# sourceMappingURL=context.d.ts.map

package/dist/context/index.d.ts

@@ -1,10 +1,2 @@
-export * from "./commands";
-export * from "./context";
-export * from "./element";
-export * from "./event";
-export * from "./query";
-export * from "./query-builder-context";
-export * from "./query-builders";
-export * from "./query-cache";
-export * from "./reactive-query";
+export { ArcContext, context, contextMerge, type ArcContextAny, } from "./context";
 //# sourceMappingURL=index.d.ts.map

package/dist/context-element/command/command-context.d.ts

@@ -0,0 +1,71 @@
+import type { ArcToken, ArcTokenAny } from "../../token/token";
+import type { $type } from "../../utils/types/get-type";
+import type { ArcContextElement } from "../context-element";
+import type { CommandProtection } from "./command-data";
+/**
+ * Build context object from query elements
+ * Each element gets its context by calling element.queryContext(adapters)
+ * Only includes elements that have queryContext method
+ */
+type QueryContext<Elements extends ArcContextElement<any>[]> = {
+    [K in Elements[number] as K["queryContext"] extends (...args: any) => any ? K["name"] : never]: K["queryContext"] extends (...args: any) => infer R ? R : never;
+};
+/**
+ * Build context object from mutation elements
+ * Each element gets its context by calling element.mutateContext(adapters)
+ * Only includes elements that have mutateContext method
+ */
+type MutationContext<Elements extends ArcContextElement<any>[]> = {
+    [K in Elements[number] as K["mutateContext"] extends (...args: any) => any ? K["name"] : never]: K["mutateContext"] extends (...args: any) => infer R ? R : never;
+};
+/**
+ * Extract token params type from a token
+ */
+type TokenParams<T extends ArcTokenAny> = T extends {
+    paramsSchema: infer P extends {
+        deserialize: (...args: any) => any;
+    };
+} ? $type<P> : Record<string, any>;
+/**
+ * Auth context type for protected commands
+ * Provides access to token params from the authenticated user
+ */
+export type AuthContext<T extends ArcTokenAny> = {
+    params: TokenParams<T>;
+    tokenName: T extends ArcToken<infer Name, any, any, any> ? Name : string;
+};
+/**
+ * Extract union of all token types from protections array
+ */
+type ProtectionTokens<Protections extends CommandProtection[]> = Protections[number]["token"];
+/**
+ * Get function type for backward compatibility
+ * Allows: ctx.get(view).findOne() or ctx.get(event).emit()
+ * Returns any for flexibility - the runtime will provide the correct context
+ */
+type GetFunction<_QueryElements extends ArcContextElement<any>[], _MutationElements extends ArcContextElement<any>[]> = {
+    get: <T extends ArcContextElement<any>>(element: T) => any;
+};
+/**
+ * Command context provided to command handlers
+ * Combines query and mutation contexts from all elements
+ *
+ * Each element is accessible by its name:
+ * - Query elements: ctx.myView.findOne(...)
+ * - Mutation elements: ctx.myEvent.emit(...)
+ * - Auth context: ctx.$auth.params (only for protected commands)
+ * - Get function: ctx.get(element) for backward compatibility
+ */
+export type ArcCommandContext<QueryElements extends ArcContextElement<any>[], MutationElements extends ArcContextElement<any>[], Protections extends CommandProtection[] = []> = QueryContext<QueryElements> & MutationContext<MutationElements> & GetFunction<QueryElements, MutationElements> & (Protections extends [] ? object : {
+    $auth: AuthContext<ProtectionTokens<Protections>>;
+});
+/**
+ * Helper type to extract command context from command data
+ */
+export type ArcCommandContextFromData<Data> = Data extends {
+    queryElements: infer Q extends ArcContextElement<any>[];
+    mutationElements: infer M extends ArcContextElement<any>[];
+    protections?: infer P extends CommandProtection[];
+} ? ArcCommandContext<Q, M, P extends undefined ? [] : P> : never;
+export {};
+//# sourceMappingURL=command-context.d.ts.map

package/dist/context-element/command/command-data.d.ts

@@ -0,0 +1,33 @@
+import type { ArcObjectAny } from "../../elements/object";
+import type { ArcTokenAny } from "../../token/token";
+import type { TokenInstanceAny } from "../../token/token-instance";
+import type { ArcContextElement } from "../context-element";
+import type { ArcCommandHandler } from "./command-handler";
+/**
+ * Protection check function for commands
+ * Receives token instance and returns whether access is allowed
+ */
+export type CommandProtectionCheck<T extends ArcTokenAny> = (tokenInstance: TokenInstanceAny) => boolean | Promise<boolean>;
+/**
+ * Protection configuration for a command
+ */
+export type CommandProtection = {
+    token: ArcTokenAny;
+    check: CommandProtectionCheck<any>;
+};
+/**
+ * Command data configuration
+ * Contains all generic types and non-generic configuration in one object
+ */
+export type ArcCommandData = {
+    name: string;
+    params: ArcObjectAny | null;
+    results: ArcObjectAny[];
+    queryElements: ArcContextElement<any>[];
+    mutationElements: ArcContextElement<any>[];
+    description?: string;
+    isPublic?: boolean;
+    handler?: ArcCommandHandler<any, any, any> | false;
+    protections?: CommandProtection[];
+};
+//# sourceMappingURL=command-data.d.ts.map

package/dist/context-element/command/command-handler.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Command handler function type
+ * Receives context and parameters, returns result
+ */
+export type ArcCommandHandler<Context, Params, Result> = (ctx: Context, params: Params) => Promise<Result> | Result;
+//# sourceMappingURL=command-handler.d.ts.map