@arcote.tech/arc 0.4.10 → 0.5.0

package/dist/context-element/function/arc-function-data.d.ts

@@ -0,0 +1,70 @@
+import type { ArcObjectAny } from "../../elements/object";
+import type { ArcToken, ArcTokenAny } from "../../token/token";
+import type { TokenInstanceAny } from "../../token/token-instance";
+import type { $type } from "../../utils/types/get-type";
+import type { ArcContextElement } from "../context-element";
+import type { ElementContext } from "../element-context";
+/**
+ * Unified protection check function.
+ *
+ * Return value determines behavior:
+ * - `false`  → access denied
+ * - `true`   → access allowed, no data filter
+ * - `Record` → access allowed + merged into WHERE clause (query context)
+ */
+export type FnProtectionCheck<T extends ArcTokenAny> = (tokenInstance: TokenInstanceAny) => boolean | Record<string, unknown> | Promise<boolean | Record<string, unknown>>;
+/**
+ * Protection configuration for an ArcFunction.
+ */
+export type FnProtection = {
+    token: ArcTokenAny;
+    check: FnProtectionCheck<any>;
+};
+/**
+ * Extract token params type from a token definition.
+ */
+type TokenParams<T extends ArcTokenAny> = T extends {
+    paramsSchema: infer P extends {
+        deserialize: (...args: any) => any;
+    };
+} ? $type<P> : Record<string, any>;
+/**
+ * Auth context injected when protectedBy() is used.
+ */
+export type FnAuthContext<T extends ArcTokenAny> = {
+    params: TokenParams<T>;
+    tokenName: T extends ArcToken<infer Name, any, any, any> ? Name : string;
+};
+/**
+ * Extract union of token types from protections array.
+ */
+type ProtectionTokens<Protections extends FnProtection[]> = Protections[number]["token"];
+/**
+ * ArcFunction data — single generic container for all function state.
+ */
+export type ArcFunctionData = {
+    params: ArcObjectAny | null;
+    result: ArcObjectAny | null;
+    queryElements: ArcContextElement<any>[];
+    mutationElements: ArcContextElement<any>[];
+    protections: FnProtection[];
+    handler: Function | false | null;
+    description?: string;
+};
+/**
+ * Unified function context — single source of truth for all handle() signatures.
+ *
+ * Computes ctx from:
+ * - query/mutate deps → ElementContext
+ * - protections → $auth
+ * - ExtraCtx → injected by wrapping element (e.g. aggregate event emitters)
+ */
+export type FnContext<Data extends ArcFunctionData, ExtraCtx = {}> = ElementContext<Data["queryElements"], Data["mutationElements"]> & (Data["protections"] extends [] ? object : {
+    $auth: FnAuthContext<ProtectionTokens<Data["protections"]>>;
+}) & ExtraCtx;
+/**
+ * Handler function type for ArcFunction.
+ */
+export type FnHandler<Data extends ArcFunctionData, ExtraCtx = {}> = (ctx: FnContext<Data, ExtraCtx>, params: Data["params"] extends ArcObjectAny ? $type<Data["params"]> : void) => Promise<Data["result"] extends ArcObjectAny ? $type<Data["result"]> : void>;
+export {};
+//# sourceMappingURL=arc-function-data.d.ts.map

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

@@ -0,0 +1,119 @@
+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 type { ArcContextElement } from "../context-element";
+import type { ArcFunctionData, FnContext, FnProtection, FnProtectionCheck } from "./arc-function-data";
+/**
+ * ArcFunction — unified composable core for all function-like elements.
+ *
+ * Manages params, result, query/mutate deps, protection, and handler
+ * in a single immutable builder. Elements (Command, Listener, Route, Tool,
+ * Aggregate methods) hold this as a private `#fn` field and delegate to it.
+ *
+ * @typeParam Data     — single generic container (Merge pattern)
+ * @typeParam ExtraCtx — additional context injected by wrapping element
+ *
+ * @example
+ * ```typescript
+ * const fn = new ArcFunction(defaultData)
+ *   .withParams({ title: string() })
+ *   .withResult({ id: string() })
+ *   .query([usersView])
+ *   .protectedBy(adminToken, t => t.canI('create'))
+ *   .handle(async (ctx, params) => {
+ *     // ctx: { query: { usersView }, $auth: { params, tokenName } }
+ *     return { id: '123' };
+ *   });
+ * ```
+ */
+export declare class ArcFunction<const Data extends ArcFunctionData, ExtraCtx = {}> {
+    readonly data: Data;
+    constructor(data: Data);
+    withParams<const S extends ArcRawShape>(schema: S | ArcObject<S>): ArcFunction<Merge<Data, {
+        params: ArcObject<S>;
+    }>, ExtraCtx>;
+    withResult<const S extends ArcRawShape>(schema: S | ArcObject<S>): ArcFunction<Merge<Data, {
+        result: ArcObject<S>;
+    }>, ExtraCtx>;
+    query<const Elements extends ArcContextElement<any>[]>(elements: Elements): ArcFunction<Merge<Data, {
+        queryElements: Elements;
+    }>, ExtraCtx>;
+    mutate<const Elements extends ArcContextElement<any>[]>(elements: Elements): ArcFunction<Merge<Data, {
+        mutationElements: Elements;
+    }>, ExtraCtx>;
+    protectedBy<T extends ArcTokenAny>(token: T, check: FnProtectionCheck<T>): ArcFunction<Merge<Data, {
+        protections: [...Data["protections"] extends infer P extends FnProtection[] ? P : [], {
+            token: T;
+            check: typeof check;
+        }];
+    }>, ExtraCtx>;
+    description<const Desc extends string>(desc: Desc): ArcFunction<Merge<Data, {
+        description: Desc;
+    }>, ExtraCtx>;
+    handle<Handler extends ((ctx: FnContext<Data, ExtraCtx>, ...args: Data["params"] extends ArcObjectAny ? [$type<Data["params"]>] : []) => Promise<any>) | false>(handler: Handler): ArcFunction<Merge<Data, {
+        handler: Handler;
+    }>, ExtraCtx>;
+    get isPublic(): boolean;
+    get hasProtections(): boolean;
+    get protections(): FnProtection[];
+    get handler(): false | Function | null;
+    get params(): ArcObjectAny | null;
+    get result(): ArcObjectAny | null;
+    /**
+     * Verify all protections pass for given token instances.
+     * All protections must pass (logical AND).
+     */
+    verifyProtections(tokens: TokenInstanceAny[]): Promise<boolean>;
+    /**
+     * Build element context from query/mutate deps.
+     * Returns { query, mutate } accessor — $auth and ExtraCtx injected by element.
+     */
+    buildContext(adapters: ModelAdapters): any;
+    /**
+     * Convert params/result schemas to JSON Schema format.
+     */
+    toJsonSchema(): {
+        params: any;
+        result: any;
+    };
+}
+export declare const defaultFunctionData: {
+    readonly params: null;
+    readonly result: null;
+    readonly queryElements: [];
+    readonly mutationElements: [];
+    readonly protections: [];
+    readonly handler: null;
+    readonly description: undefined;
+};
+export type DefaultFunctionData = typeof defaultFunctionData;
+/**
+ * Create a new ArcFunction with default empty state.
+ */
+export declare function arcFunction(): ArcFunction<{
+    readonly params: null;
+    readonly result: null;
+    readonly queryElements: [];
+    readonly mutationElements: [];
+    readonly protections: [];
+    readonly handler: null;
+    readonly description: undefined;
+}, {}>;
+/**
+ * Create an ArcFunction with a pre-set ExtraCtx type.
+ * Used by aggregates to inject event emitters / $query into the context.
+ */
+export declare function arcFunctionWithCtx<ExtraCtx>(): ArcFunction<{
+    readonly params: null;
+    readonly result: null;
+    readonly queryElements: [];
+    readonly mutationElements: [];
+    readonly protections: [];
+    readonly handler: null;
+    readonly description: undefined;
+}, ExtraCtx>;
+//# sourceMappingURL=arc-function.d.ts.map

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

@@ -0,0 +1,3 @@
+export * from "./arc-function";
+export * from "./arc-function-data";
+//# sourceMappingURL=index.d.ts.map

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

@@ -8,6 +8,7 @@ export * from "./command";
 export * from "./context-element";
 export * from "./element-context";
 export * from "./event";
+export * from "./function";
 export * from "./listener";
 export * from "./route";
 export * from "./static-view";

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

@@ -1,8 +1,10 @@
 import type { ModelAdapters } from "../../model/model-adapters";
 import type { Merge } from "../../utils";
 import { ArcContextElement, type ArcEnvironment } from "../context-element";
+import type { ElementContext } from "../element-context";
 import type { ArcEventAny } from "../event/event";
 import type { ArcEventInstance } from "../event/instance";
+import { ArcFunction } from "../function/arc-function";
 /**
  * Listener Data - Configuration for a listener
  */
@@ -16,27 +18,9 @@ export interface ArcListenerData {
     isAsync: boolean;
 }
 /**
- * Listener Context - Available to listener handlers
+ * Listener Context - derived from ArcFunction's query/mutate deps
  */
-export type ArcListenerContext<QueryElements extends ArcContextElement<any>[], MutationElements extends ArcContextElement<any>[]> = {
-    [K in QueryElements[number] as K["name"]]: K extends {
-        queryContext: (adapters: ModelAdapters) => infer R;
-    } ? R : never;
-} & {
-    [K in MutationElements[number] as K["name"]]: K extends {
-        mutateContext: (adapters: ModelAdapters) => infer R;
-    } ? R : never;
-} & {
-    get: <T extends ArcContextElement<any>>(element: T) => T extends {
-        queryContext: (adapters: ModelAdapters) => infer R;
-    } ? R : T extends {
-        mutateContext: (adapters: ModelAdapters) => infer R;
-    } ? R : never;
-    $auth?: {
-        params: any;
-        tokenName: string;
-    };
-};
+export type ArcListenerContext<QueryElements extends ArcContextElement<any>[], MutationElements extends ArcContextElement<any>[]> = ElementContext<QueryElements, MutationElements>;
 /**
  * Listener Handler - Function that handles events
  */
@@ -44,12 +28,8 @@ export type ArcListenerHandler<Context, EventElements extends ArcEventAny[]> = (
 /**
  * Arc Listener - Reactive side effect triggered by events
  *
- * Listeners react to events and can:
- * - Query state through query elements (views)
- * - Mutate state through mutation elements (events, commands)
- * - Run synchronously (blocking) or asynchronously (fire-and-forget)
- *
- * Listeners only run on the server.
+ * Uses ArcFunction internally (#fn) for unified query/mutate deps
+ * and context building. handle() is Listener-specific (event as 2nd arg).
  *
  * @example
  * ```typescript
@@ -58,104 +38,46 @@ export type ArcListenerHandler<Context, EventElements extends ArcEventAny[]> = (
  *   .query([usersView])
  *   .mutate([notificationSentEvent])
  *   .handle(async (ctx, event) => {
- *     const user = await ctx.usersView.findOne({ _id: event.payload.assignedTo });
+ *     const user = await ctx.query.usersView.findOne({ _id: event.payload.assignedTo });
  *     if (user) {
- *       await ctx.notificationSentEvent.emit({ userId: user._id, message: "New task!" });
+ *       await ctx.mutate.notificationSentEvent.emit({ userId: user._id, message: "New task!" });
  *     }
  *   });
  * ```
  */
 export declare class ArcListener<const Data extends ArcListenerData> extends ArcContextElement<Data["name"]> {
+    #private;
     private readonly data;
     private unsubscribers;
-    constructor(data: Data);
-    /**
-     * Set listener description for documentation
-     */
+    constructor(data: Data, fn?: ArcFunction<any>);
     description<const Desc extends string>(description: Desc): ArcListener<Merge<Data, {
         description: Desc;
     }>>;
-    /**
-     * Specify which events this listener reacts to
-     *
-     * @param events - Array of event elements to listen to
-     */
     listenTo<const Events extends ArcEventAny[]>(events: Events): ArcListener<Merge<Data, {
         eventElements: Events;
     }>>;
-    /**
-     * Add query elements (views) that this listener needs to read from
-     *
-     * @param elements - Array of view elements to query
-     */
     query<const Elements extends ArcContextElement<any>[]>(elements: Elements): ArcListener<Merge<Data, {
         queryElements: Elements;
     }>>;
-    /**
-     * Add mutation elements (events, commands) that this listener needs to modify state
-     *
-     * @param elements - Array of event/command elements to mutate with
-     */
     mutate<const Elements extends ArcContextElement<any>[]>(elements: Elements): ArcListener<Merge<Data, {
         mutationElements: Elements;
     }>>;
-    /**
-     * Mark listener as async (fire-and-forget)
-     * Async listeners don't block event processing
-     */
     async(): ArcListener<Merge<Data, {
         isAsync: true;
     }>>;
     /**
-     * Set the handler function for this listener
-     *
-     * @param handler - Function that handles events
+     * Set the handler function for this listener.
+     * ctx is computed from #fn's query/mutate deps, event typed from listenTo().
      */
     handle<Handler extends ArcListenerHandler<ArcListenerContext<Data["queryElements"], Data["mutationElements"]>, Data["eventElements"]>>(handler: Handler): ArcListener<Merge<Data, {
         handler: Handler;
     }>>;
-    /**
-     * Get the events this listener is subscribed to
-     */
     get eventElements(): ArcEventAny[];
-    /**
-     * Check if listener is async
-     */
     get isAsync(): boolean;
-    /**
-     * Initialize listener - subscribe to events
-     * Only runs on server
-     */
     init(environment: ArcEnvironment, adapters: ModelAdapters): Promise<void>;
-    /**
-     * Handle an incoming event
-     */
     private handleEvent;
-    /**
-     * Build listener context with access to query and mutation elements
-     */
-    private buildListenerContext;
-    /**
-     * Cleanup - unsubscribe from all events
-     */
     destroy(): void;
 }
-/**
- * Create a new listener with the given name
- *
- * @param name - Unique listener name
- * @returns New listener instance ready for configuration
- *
- * @example
- * ```typescript
- * const myListener = listener("myListener")
- *   .listenTo([someEvent])
- *   .mutate([anotherEvent])
- *   .handle(async (ctx, event) => {
- *     await ctx.anotherEvent.emit({ ... });
- *   });
- * ```
- */
 export declare function listener<const Name extends string>(name: Name): ArcListener<{
     readonly name: Name;
     readonly eventElements: [];
@@ -163,8 +85,5 @@ export declare function listener<const Name extends string>(name: Name): ArcList
     readonly mutationElements: [];
     readonly isAsync: false;
 }>;
-/**
- * Type alias for any listener (used in collections)
- */
 export type ArcListenerAny = ArcListener<any>;
 //# sourceMappingURL=listener.d.ts.map

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

@@ -3,16 +3,14 @@ import type { ArcTokenAny } from "../../token/token";
 import type { TokenInstanceAny } from "../../token/token-instance";
 import type { Merge } from "../../utils";
 import { ArcContextElement } from "../context-element";
-import { type ElementContext } from "../element-context";
+import type { ElementContext } from "../element-context";
+import { ArcFunction } from "../function/arc-function";
 import type { ArcRouteData, HttpMethod, RouteHandler, RouteHandlers, RouteProtectionCheck } from "./route-data";
 /**
  * Arc Route - Custom HTTP endpoint handler
  *
- * Routes allow defining custom HTTP endpoints that can:
- * - Handle GET, POST, PUT, DELETE, PATCH requests
- * - Access views (query) and events/commands (mutate)
- * - Be public or protected by tokens
- * - Use path parameters (e.g., /users/:userId)
+ * Uses ArcFunction internally (#fn) for unified query/mutate deps,
+ * protection, and context building.
  *
  * @example
  * ```typescript
@@ -22,57 +20,32 @@ import type { ArcRouteData, HttpMethod, RouteHandler, RouteHandlers, RouteProtec
  *   .mutate([orderPaidEvent])
  *   .handle({
  *     POST: async (ctx, req) => {
- *       const body = await req.json();
- *       await ctx.orderPaidEvent.emit({ ... });
+ *       await ctx.mutate.orderPaidEvent.emit({ ... });
  *       return new Response("OK");
  *     }
  *   });
  * ```
  */
 export declare class ArcRoute<const Data extends ArcRouteData> extends ArcContextElement<Data["name"]> {
+    #private;
     private readonly data;
-    constructor(data: Data);
-    /**
-     * Set route description
-     */
+    constructor(data: Data, fn?: ArcFunction<any>);
     description<const Desc extends string>(description: Desc): ArcRoute<Merge<Data, {
         description: Desc;
     }>>;
-    /**
-     * Set route path pattern
-     * Supports path parameters like /users/:userId
-     * Path will be prefixed with /route automatically
-     */
     path<const P extends string>(path: P): ArcRoute<Merge<Data, {
         path: P;
     }>>;
-    /**
-     * Mark route as public (no authentication required)
-     */
     public(): ArcRoute<Merge<Data, {
         isPublic: true;
     }>>;
-    /**
-     * Add query elements (views) that this route can read from
-     */
     query<const Elements extends ArcContextElement<any>[]>(elements: Elements): ArcRoute<Merge<Data, {
         queryElements: Elements;
     }>>;
-    /**
-     * Add mutation elements (events, commands) that this route can use
-     */
     mutate<const Elements extends ArcContextElement<any>[]>(elements: Elements): ArcRoute<Merge<Data, {
         mutationElements: Elements;
     }>>;
-    /**
-     * Add token-based protection to this route
-     * Check function returns true to allow, false to deny
-     * Token params available in ctx.$auth
-     */
     protectBy<T extends ArcTokenAny>(token: T, check: RouteProtectionCheck<T>): ArcRoute<Data>;
-    /**
-     * Set route handlers for HTTP methods
-     */
     handle<Handlers extends RouteHandlers<ElementContext<Data["queryElements"], Data["mutationElements"]> & {
         $auth?: {
             params: Record<string, any>;
@@ -81,53 +54,22 @@ export declare class ArcRoute<const Data extends ArcRouteData> extends ArcContex
     }>>(handlers: Handlers): ArcRoute<Merge<Data, {
         handlers: Handlers;
     }>>;
-    /**
-     * Get the route path (without /route prefix)
-     */
     get routePath(): string;
-    /**
-     * Get the full route path (with /route prefix)
-     */
     get fullPath(): string;
-    /**
-     * Check if route is public
-     */
     get isPublic(): boolean;
-    /**
-     * Check if route has protections
-     */
     get hasProtections(): boolean;
-    /**
-     * Get all protection configurations
-     */
     get protections(): import("./route-data").RouteProtection[];
-    /**
-     * Get handler for a specific HTTP method
-     */
     getHandler(method: HttpMethod): RouteHandler<any> | undefined;
-    /**
-     * Check if a pathname matches this route's path pattern
-     * Returns match result with extracted params
-     */
     matchesPath(pathname: string): {
         matches: boolean;
         params: Record<string, string>;
     };
-    /**
-     * Verify all protections pass for given token instances
-     */
     verifyProtections(tokens: TokenInstanceAny[]): Promise<boolean>;
-    /**
-     * Build route context with access to query and mutation elements
-     */
     buildContext(adapters: ModelAdapters, authParams?: {
         params: Record<string, any>;
         tokenName: string;
     }): any;
 }
-/**
- * Create a new route with the given name
- */
 export declare function route<const Name extends string>(name: Name): ArcRoute<{
     name: Name;
     path: undefined;
@@ -138,8 +80,5 @@ export declare function route<const Name extends string>(name: Name): ArcRoute<{
     protections: [];
     isPublic: false;
 }>;
-/**
- * Type alias for any route
- */
 export type ArcRouteAny = ArcRoute<any>;
 //# sourceMappingURL=route.d.ts.map

package/dist/elements/object.d.ts

@@ -1,6 +1,6 @@
 import type { DatabaseAgnosticColumnInfo } from "../data-storage/database-store";
 import type { FirstArgument } from "../utils/types/first-argument";
-import type { AddQuestionMarks } from "../utils";
+import type { AddQuestionMarks, Simplify } from "../utils";
 import { ArcAbstract, type Validators } from "./abstract";
 import type { ArcElement } from "./element";
 import { ArcOptional } from "./optional";
@@ -35,11 +35,11 @@ export declare class ArcObject<E extends ArcRawShape, V extends Validators = [
     }): {
         [key in keyof E]: ReturnType<E[key]["serialize"]>;
     };
-    deserialize(value: AddQuestionMarks<{
+    deserialize(value: Simplify<AddQuestionMarks<{
         [key in keyof E]: FirstArgument<E[key]["deserialize"]>;
-    }>): AddQuestionMarks<{
+    }>>): Simplify<AddQuestionMarks<{
         [key in keyof E]: ReturnType<E[key]["deserialize"]>;
-    }>;
+    }>>;
     deserializePath(path: string[], value: any): any;
     parsePartial(value: Partial<{
         [key in keyof E]: FirstArgument<E[key]["parse"]>;