@arcote.tech/arc 0.1.12 → 0.3.0

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

@@ -0,0 +1,198 @@
+import type { ArcObjectAny, ArcRawShape } from "../../elements/object";
+import { ArcObject } from "../../elements/object";
+import type { ModelAdapters } from "../../model/model-adapters";
+import type { ArcTokenAny } from "../../token/token";
+import type { TokenInstanceAny } from "../../token/token-instance";
+import type { Merge } from "../../utils";
+import type { $type } from "../../utils/types/get-type";
+import { ArcContextElement } from "../context-element";
+import type { ArcCommandContextFromData } from "./command-context";
+import type { ArcCommandData, CommandProtection, CommandProtectionCheck } from "./command-data";
+import type { ArcCommandHandler } from "./command-handler";
+/**
+ * Arc Command - Business action that modifies state
+ *
+ * Commands are the primary way to execute business logic in Arc Framework.
+ * They can:
+ * - Accept typed parameters
+ * - Return typed results
+ * - Query state through query elements (views)
+ * - Mutate state through mutation elements (events, other commands)
+ *
+ * Commands follow the factory pattern from the Arc guide:
+ * - All configuration in a single Data object
+ * - Type-safe throughout
+ * - Immutable with clone-on-modify
+ * - Separate query and mutation concerns
+ *
+ * @example
+ * ```typescript
+ * const registerCmd = command("register")
+ *   .public()
+ *   .query([usersView])
+ *   .mutate([userRegisteredEvent])
+ *   .withParams({ email: string(), password: string() })
+ *   .withResult({ success: boolean() })
+ *   .handle(async (ctx, params) => {
+ *     // Business logic here
+ *     return { success: true };
+ *   });
+ * ```
+ */
+export declare class ArcCommand<const Data extends ArcCommandData> extends ArcContextElement<Data["name"]> {
+    private readonly data;
+    constructor(data: Data);
+    /**
+     * Set command description for documentation and tooling
+     */
+    description<const Desc extends string>(description: Desc): ArcCommand<Merge<Data, {
+        description: Desc;
+    }>>;
+    /**
+     * Check if command is public (no protections = public)
+     * Commands without protectBy() are considered public
+     */
+    get isPublic(): boolean;
+    /**
+     * Add query elements (views) that this command needs to read from
+     * Query elements provide read-only access to state
+     *
+     * @param elements - Array of view elements to query
+     */
+    query<const Elements extends ArcContextElement<any>[]>(elements: Elements): ArcCommand<Merge<Data, {
+        queryElements: Elements;
+    }>>;
+    /**
+     * Add mutation elements (events, commands) that this command needs to modify state
+     * Mutation elements provide write access to state
+     *
+     * @param elements - Array of event/command elements to mutate with
+     */
+    mutate<const Elements extends ArcContextElement<any>[]>(elements: Elements): ArcCommand<Merge<Data, {
+        mutationElements: Elements;
+    }>>;
+    /**
+     * Define command parameters schema
+     *
+     * @param schema - Object schema or raw shape defining parameter structure
+     */
+    withParams<NewParams extends ArcRawShape>(schema: NewParams | ArcObject<NewParams>): ArcCommand<Merge<Data, {
+        params: ArcObject<NewParams>;
+    }>>;
+    /**
+     * Define command result schemas
+     * Commands can return multiple result types (success, error variants)
+     *
+     * @param schemas - Array of object schemas for possible results
+     */
+    withResult<NewResults extends ArcRawShape[]>(...schemas: NewResults): ArcCommand<Merge<Data, {
+        results: { [K in keyof NewResults]: ArcObject<NewResults[K]>; };
+    }>>;
+    /**
+     * Set command handler function
+     * The handler contains the business logic for this command
+     *
+     * @param handler - Function that executes command logic, or false to disable
+     */
+    handle<Handler extends ArcCommandHandler<ArcCommandContextFromData<Data>, Data["params"] extends ArcObjectAny ? $type<Data["params"]> : null, $type<Data["results"][number]>> | false>(handler: Handler): ArcCommand<Merge<Data, {
+        handler: Handler;
+    }>>;
+    /**
+     * Add token-based protection to this command
+     * Multiple protections can be added (all must pass)
+     *
+     * @param token - Token definition to protect with
+     * @param check - Function to check if access is allowed
+     *
+     * @example
+     * ```typescript
+     * command("editForm")
+     *   .protectBy(moderatorToken, (token) => token.canI('form:edit'))
+     *   .handle(async (ctx, params) => { ... });
+     * ```
+     */
+    protectBy<T extends ArcTokenAny>(token: T, check: CommandProtectionCheck<T>): ArcCommand<Merge<Data, {
+        protections: [...Data["protections"] extends infer P extends CommandProtection[] ? P : [], {
+            token: T;
+            check: typeof check;
+        }];
+    }>>;
+    /**
+     * Check if command has protections
+     */
+    get hasProtections(): boolean;
+    /**
+     * Get all protection configurations
+     */
+    get protections(): CommandProtection[];
+    /**
+     * Verify all protections pass for given token instances
+     *
+     * @param tokens - Array of token instances to verify
+     * @returns true if all protections pass
+     */
+    verifyProtections(tokens: TokenInstanceAny[]): Promise<boolean>;
+    /**
+     * Initialize command in the given environment
+     * On server: registers command handler for remote execution
+     */
+    init(environment: import("../context-element").ArcEnvironment, adapters: ModelAdapters): Promise<void>;
+    /**
+     * Generate mutation context for this command
+     * Provides execute functionality to run the command
+     *
+     * @param adapters - Available adapters (storage, commandWire, eventPublisher)
+     * @returns Context object with execute method
+     */
+    mutateContext(adapters: ModelAdapters): ((params: Data["params"] extends ArcObjectAny ? $type<Data["params"]> : null) => Promise<$type<Data["results"][number]>>) & {
+        params: Data["params"];
+    };
+    /**
+     * Execute command locally with handler
+     * Collects events and publishes them via eventPublisher
+     */
+    private executeLocally;
+    /**
+     * Build command context with access to query and mutation elements
+     */
+    private buildCommandContext;
+    /**
+     * Convert command to JSON Schema format
+     * Used for OpenAPI documentation and validation
+     */
+    toJsonSchema(): {
+        type: string;
+        name: string;
+        description: string | undefined;
+        parameters: any;
+        strict: boolean;
+    };
+}
+/**
+ * Create a new command with the given name
+ *
+ * @param name - Unique command name
+ * @returns New command instance ready for configuration
+ *
+ * @example
+ * ```typescript
+ * const myCommand = command("myCommand")
+ *   .withParams({ input: string() })
+ *   .handle(async (ctx, params) => {
+ *     // logic here
+ *   });
+ * ```
+ */
+export declare function command<const Name extends string>(name: Name): ArcCommand<{
+    readonly name: Name;
+    readonly params: null;
+    readonly results: [];
+    readonly queryElements: [];
+    readonly mutationElements: [];
+    readonly protections: [];
+}>;
+/**
+ * Type alias for any command (used in collections)
+ */
+export type ArcCommandAny = ArcCommand<any>;
+//# sourceMappingURL=command.d.ts.map

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

@@ -0,0 +1,6 @@
+export { ArcCommand, command, type ArcCommandAny } from "./command";
+export type { ArcCommandContext, ArcCommandContextFromData, AuthContext, } from "./command-context";
+export type { ArcCommandData, CommandProtection, CommandProtectionCheck, } from "./command-data";
+export type { ArcCommandHandler } from "./command-handler";
+export type { ArcObjectAny, ArcRawShape } from "../../elements/object";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,75 @@
+/**
+ * Context Element - Core building block of Arc Framework
+ *
+ * Every element in Arc (command, event, view, listener) extends this base class.
+ * Elements provide type-safe access to their functionality through the context system.
+ */
+import type { ModelAdapters } from "../model/model-adapters";
+export type ArcEnvironment = "client" | "server" | "universal";
+/**
+ * Base class for all Arc context elements
+ *
+ * Elements are the building blocks of Arc Framework:
+ * - Commands: Business actions that modify state
+ * - Events: Records of what happened
+ * - Views: Read models derived from events
+ * - Listeners: Side effects triggered by events
+ *
+ * Each element declares:
+ * 1. Its name (for identification)
+ * 2. Its context generation logic
+ * 3. Its handler/logic
+ */
+export declare abstract class ArcContextElement<const Name extends string> {
+    /**
+     * Element name - used for identification and error messages
+     * Must be unique within a context
+     */
+    readonly name: Name;
+    constructor(name: Name);
+    /**
+     * Initialize element in the given environment
+     * Called by Model when context is created
+     *
+     * Use this to:
+     * - Register server-side handlers
+     * - Set up subscriptions
+     * - Initialize adapters
+     *
+     * @param environment - Current execution environment
+     * @param adapters - Available adapters
+     */
+    init?(environment: ArcEnvironment, adapters: ModelAdapters): void | Promise<void>;
+    /**
+     * Get the mutation context for this element
+     * Provides write operations (emit events, execute commands, etc.)
+     *
+     * @param adapters - Available adapters (storage, leaderConnection)
+     * @returns Mutation context with write methods, or undefined if not supported
+     *
+     * Example implementations:
+     * - Events: { emit: (payload) => Promise<void> }
+     * - Commands: { execute: (params) => Promise<result> }
+     */
+    mutateContext?(adapters: ModelAdapters): unknown;
+    /**
+     * Get the query context for this element
+     * Provides read operations (query views, read state, etc.)
+     *
+     * @param adapters - Available adapters (storage, leaderConnection)
+     * @returns Query context with read methods, or undefined if not supported
+     *
+     * Example implementations:
+     * - Views: { findOne: (query) => Promise<data>, findMany: (query) => Promise<data[]> }
+     */
+    queryContext?(adapters: ModelAdapters): unknown;
+}
+/**
+ * Type helper to extract element name from element type
+ */
+export type ArcContextElementName<E extends ArcContextElement<any>> = E extends ArcContextElement<infer N> ? N : never;
+/**
+ * Type for any context element (used for collections)
+ */
+export type ArcContextElementAny = ArcContextElement<string>;
+//# sourceMappingURL=context-element.d.ts.map

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

@@ -0,0 +1,35 @@
+import type { WhereCondition } from "../../data-storage/find-options";
+import type { ArcObjectAny } from "../../elements/object";
+import type { ArcTokenAny } from "../../token/token";
+/**
+ * Protection config for events
+ * Defines read/write access conditions based on token params
+ */
+export type EventProtectionConfig = {
+    read: WhereCondition | false;
+    write: WhereCondition | false;
+};
+/**
+ * Protection function for events
+ * Receives token params and returns read/write conditions
+ */
+export type EventProtectionFn<TokenParams> = (params: TokenParams) => EventProtectionConfig;
+/**
+ * Event protection configuration
+ */
+export type EventProtection = {
+    token: ArcTokenAny;
+    protectionFn: EventProtectionFn<any>;
+};
+/**
+ * Event data configuration
+ * Contains all generic types and non-generic configuration in one object
+ */
+export type ArcEventData = {
+    name: string;
+    payload: ArcObjectAny | undefined;
+    description?: string;
+    protections?: EventProtection[];
+    tagFields?: string[];
+};
+//# sourceMappingURL=event-data.d.ts.map

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

@@ -0,0 +1,158 @@
+import type { DatabaseStoreSchema } from "../../data-storage/database-store";
+import { ArcObject, type ArcObjectAny, type ArcRawShape } from "../../elements/object";
+import type { ModelAdapters } from "../../model/model-adapters";
+import type { ArcTokenAny } from "../../token/token";
+import type { TokenInstanceAny } from "../../token/token-instance";
+import type { Merge } from "../../utils";
+import type { $type } from "../../utils/types/get-type";
+import { ArcContextElement } from "../context-element";
+import type { ArcEventData, EventProtectionFn } from "./event-data";
+/**
+ * Arc Event - Record of something that happened
+ *
+ * Events are immutable records of state changes in Arc Framework.
+ * They:
+ * - Have a unique name/type
+ * - Carry a typed payload
+ * - Are append-only (never modified or deleted)
+ * - Drive view updates and listener reactions
+ *
+ * Events follow the factory pattern from the Arc guide:
+ * - All configuration in a single Data object
+ * - Type-safe throughout
+ * - Immutable with clone-on-modify
+ *
+ * @example
+ * ```typescript
+ * const userRegistered = event("userRegistered", {
+ *   userId: string().branded("user-id"),
+ *   email: string().email(),
+ *   timestamp: date(),
+ * });
+ * ```
+ */
+export declare class ArcEvent<const Data extends ArcEventData> extends ArcContextElement<Data["name"]> {
+    private readonly data;
+    private readonly eventId;
+    constructor(data: Data);
+    /**
+     * Get event payload schema
+     */
+    get payload(): Data["payload"];
+    /**
+     * Set event description for documentation
+     */
+    description<const Desc extends string>(description: Desc): ArcEvent<Merge<Data, {
+        description: Desc;
+    }>>;
+    /**
+     * Generate mutation context for this event
+     * Provides emit functionality to publish event instances
+     *
+     * @param adapters - Available adapters (eventPublisher, dataStorage)
+     * @returns Context object with emit method
+     */
+    mutateContext(adapters: ModelAdapters): {
+        emit: (payload: Data["payload"] extends ArcObjectAny ? $type<Data["payload"]> : undefined) => Promise<void>;
+    };
+    /**
+     * Add token-based protection to this event
+     * Defines read/write access conditions based on token params
+     *
+     * @param token - Token definition to protect with
+     * @param protectionFn - Function returning read/write conditions
+     *
+     * @example
+     * ```typescript
+     * event("taskCreated", taskPayload)
+     *   .protectBy(userToken, (params) => ({
+     *     read: { userId: params.userId },  // Can only read own events
+     *     write: { userId: params.userId }, // Can only emit own events
+     *   }));
+     * ```
+     */
+    protectBy<T extends ArcTokenAny>(token: T, protectionFn: EventProtectionFn<any>): ArcEvent<Data>;
+    /**
+     * Check if event has protections
+     */
+    get hasProtections(): boolean;
+    /**
+     * Get all protection configurations
+     */
+    get protections(): import("./event-data").EventProtection[];
+    /**
+     * Get protection config for a specific token instance
+     *
+     * @param tokenInstance - Token instance to get protection for
+     * @returns Protection config or null if no matching protection
+     */
+    getProtectionFor(tokenInstance: TokenInstanceAny): {
+        read: any;
+        write: any;
+    } | null;
+    /**
+     * Specify which payload fields should be stored as tags for efficient querying
+     * Tags are stored in a separate table with foreign key to events
+     *
+     * @param tagFields - Array of payload field names to use as tags
+     *
+     * @example
+     * ```typescript
+     * event("taskCreated", { taskId: string(), userId: string(), title: string() })
+     *   .tags(["userId", "taskId"]); // userId and taskId become queryable tags
+     * ```
+     */
+    tags<TagFields extends string[]>(tagFields: TagFields): ArcEvent<Merge<Data, {
+        tagFields: TagFields;
+    }>>;
+    /**
+     * Get the tag fields for this event
+     */
+    get tagFields(): string[];
+    /** Cached shared schema - created once and reused */
+    private static _sharedSchema;
+    /**
+     * Get the shared database store schema for all events
+     * All events are stored in the same tables, distinguished by the `type` field
+     *
+     * Returns 3 tables:
+     * - events - single table for ALL events
+     * - event_tags - tags with FK to events
+     * - event_sync_status - sync tracking
+     */
+    static sharedDatabaseStoreSchema(): DatabaseStoreSchema;
+    /**
+     * Instance method that returns the shared schema
+     * This ensures all events share the same table structure
+     */
+    databaseStoreSchema(): DatabaseStoreSchema;
+}
+/**
+ * Create a new event with the given name and payload schema
+ *
+ * @param name - Unique event name/type
+ * @param payload - Optional payload schema (raw shape or ArcObject)
+ * @returns New event instance ready for configuration
+ *
+ * @example
+ * ```typescript
+ * // Event with payload
+ * const taskCreated = event("taskCreated", {
+ *   taskId: string(),
+ *   title: string(),
+ * });
+ *
+ * // Event without payload
+ * const systemStarted = event("systemStarted");
+ * ```
+ */
+export declare function event<const Name extends string, PayloadShape extends ArcObjectAny | ArcRawShape | undefined = undefined>(name: Name, payload?: PayloadShape): ArcEvent<{
+    name: Name;
+    payload: PayloadShape extends ArcRawShape ? ArcObject<PayloadShape> : PayloadShape extends ArcObjectAny ? PayloadShape : undefined;
+    protections: [];
+}>;
+/**
+ * Type alias for any event (used in collections)
+ */
+export type ArcEventAny = ArcEvent<any>;
+//# sourceMappingURL=event.d.ts.map

package/dist/context-element/event/index.d.ts

@@ -0,0 +1,5 @@
+export { ArcEvent, event, type ArcEventAny } from "./event";
+export type { ArcEventData } from "./event-data";
+export type { ArcEventInstance, ArcEventPayload, EventMetadata, } from "./instance";
+export type { ArcObjectAny, ArcRawShape } from "../../elements/object";
+//# sourceMappingURL=index.d.ts.map

package/dist/context-element/event/instance.d.ts

@@ -0,0 +1,26 @@
+import type { $type } from "../../utils/types/get-type";
+import type { ArcEventAny } from "./event";
+/**
+ * Event metadata attached to every event instance
+ */
+export type EventMetadata = {
+    id: string;
+    createdAt: Date;
+};
+/**
+ * Event instance type - represents an actual event occurrence
+ * Combines event type, payload, and metadata
+ */
+export type ArcEventInstance<Event extends ArcEventAny> = {
+    type: Event["name"];
+    payload: Event["payload"] extends {
+        deserialize: (...args: any) => any;
+    } ? $type<Event["payload"]> : undefined;
+} & EventMetadata;
+/**
+ * Helper type to extract event payload type
+ */
+export type ArcEventPayload<Event extends ArcEventAny> = Event["payload"] extends {
+    deserialize: (...args: any) => any;
+} ? $type<Event["payload"]> : undefined;
+//# sourceMappingURL=instance.d.ts.map

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

@@ -0,0 +1,10 @@
+/**
+ * Context module
+ *
+ * Provides dependency injection and element registration
+ */
+export * from "./context-element";
+export * from "./command";
+export * from "./event";
+export * from "./view";
+//# sourceMappingURL=index.d.ts.map

package/dist/context-element/view/index.d.ts

@@ -0,0 +1,5 @@
+export { ArcView, view, type ArcViewAny, type ArcViewRecord } from "./view";
+export type { ArcViewData } from "./view-data";
+export type { ArcViewHandlerContext, ArcViewItem, ArcViewQueryContext, } from "./view-context";
+export type { ArcObjectAny } from "../../elements/object";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,51 @@
+import type { ArcIdAny } from "../../elements/id";
+import type { ArcObjectAny } from "../../elements/object";
+import type { $type } from "../../utils/types/get-type";
+/**
+ * Request context available in view handlers
+ * Contains information about the current request (e.g., IP address)
+ */
+export type ViewRequestContext = {
+    /** Client IP address (available in server context) */
+    ipAddress?: string;
+    /** Additional request metadata */
+    [key: string]: any;
+};
+/**
+ * View handler context provided to event handlers
+ * Allows handlers to modify view state in response to events
+ */
+export type ArcViewHandlerContext<Id extends ArcIdAny, Schema extends ArcObjectAny> = {
+    /** Set a complete record in the view (create or replace) */
+    set: (id: $type<Id>, data: $type<Schema>) => Promise<void>;
+    /** Modify specific fields of an existing record */
+    modify: (id: $type<Id>, data: Partial<$type<Schema>>) => Promise<void>;
+    /** Remove a record from the view */
+    remove: (id: $type<Id>) => Promise<void>;
+    /** Find multiple records matching criteria */
+    find: (options: any) => Promise<ArcViewItem<Id, Schema>[]>;
+    /** Find a single record matching criteria */
+    findOne: (where: any) => Promise<ArcViewItem<Id, Schema> | undefined>;
+    /** Request context (IP address, etc.) - available in server context */
+    $auth: ViewRequestContext;
+};
+/**
+ * View item type - represents a single record in the view
+ * Includes the ID field (_id) plus all schema fields
+ */
+export type ArcViewItem<Id extends ArcIdAny, Schema extends ArcObjectAny> = {
+    _id: $type<Id>;
+} & $type<Schema>;
+/**
+ * View query context provided to commands
+ * Allows commands to read from views
+ */
+export type ArcViewQueryContext<Id extends ArcIdAny, Schema extends ArcObjectAny> = {
+    /** Find multiple records matching criteria */
+    find: (options: any) => Promise<ArcViewItem<Id, Schema>[]>;
+    /** Find a single record matching criteria */
+    findOne: (where: any) => Promise<ArcViewItem<Id, Schema> | undefined>;
+    /** Subscribe to view changes (optional, for reactive queries) */
+    subscribe?: (options: any, callback: (data: ArcViewItem<Id, Schema>[]) => void) => () => void;
+};
+//# sourceMappingURL=view-context.d.ts.map

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

@@ -0,0 +1,40 @@
+import type { WhereCondition } from "../../data-storage/find-options";
+import type { ArcObjectAny } from "../../elements/object";
+import type { ArcTokenAny } from "../../token/token";
+import type { ArcContextElement } from "../context-element";
+/**
+ * Protection config for views
+ * Defines read/write access conditions based on token params
+ */
+export type ViewProtectionConfig = {
+    read: WhereCondition | false;
+    write: WhereCondition | false;
+};
+/**
+ * Protection function for views
+ * Receives token params and returns read/write conditions
+ */
+export type ViewProtectionFn<TokenParams> = (params: TokenParams) => ViewProtectionConfig;
+/**
+ * View protection configuration
+ */
+export type ViewProtection = {
+    token: ArcTokenAny;
+    protectionFn: ViewProtectionFn<any>;
+};
+/**
+ * View data configuration
+ * Contains all generic types and non-generic configuration in one object
+ */
+export type ArcViewData = {
+    name: string;
+    id: any;
+    schema: ArcObjectAny;
+    elements: ArcContextElement<any>[];
+    handler: Record<string, (ctx: any, event: any) => Promise<void>>;
+    description?: string;
+    isAsync?: boolean;
+    version?: number;
+    protections?: ViewProtection[];
+};
+//# sourceMappingURL=view-data.d.ts.map