@jaypie/fabric 0.1.0

package/dist/cjs/http/types.d.ts

@@ -0,0 +1,343 @@
+import type { Service, ServiceConfig } from "../types.js";
+/**
+ * HTTP request context passed to the `http` transformation function
+ */
+export interface HttpContext {
+    /** Parsed request body */
+    body: unknown;
+    /** Request headers */
+    headers: Headers;
+    /** HTTP method (GET, POST, PUT, DELETE, PATCH) */
+    method: string;
+    /** URL path */
+    path: string;
+    /** Query string parameters */
+    query: URLSearchParams;
+    /** Path parameters extracted from route pattern (e.g., :id) */
+    params: Record<string, string>;
+}
+/**
+ * Function that transforms HTTP context to fabric service input
+ */
+export type HttpTransformFunction<TInput = Record<string, unknown>> = (context: HttpContext) => TInput | Promise<TInput>;
+/**
+ * Authorization function that validates a token and returns auth context
+ * Token is extracted from Authorization header with Bearer prefix removed
+ */
+export type AuthorizationFunction<TAuth = unknown> = (token: string) => TAuth | Promise<TAuth>;
+/**
+ * Authorization configuration - either a function or false for public endpoints
+ */
+export type AuthorizationConfig<TAuth = unknown> = AuthorizationFunction<TAuth> | false;
+/**
+ * CORS configuration options
+ */
+export interface CorsConfig {
+    /** Allowed origins - "*" for all, or array of specific origins */
+    origin?: string | string[];
+    /** Allow credentials (Access-Control-Allow-Credentials) */
+    credentials?: boolean;
+    /** Additional allowed headers (Access-Control-Allow-Headers) */
+    headers?: string[];
+    /** Headers to expose to the client (Access-Control-Expose-Headers) */
+    exposeHeaders?: string[];
+    /** Preflight cache duration in seconds (Access-Control-Max-Age) */
+    maxAge?: number;
+}
+/**
+ * CORS configuration - object config, true for defaults, or false to disable
+ */
+export type CorsOption = CorsConfig | boolean;
+/**
+ * Resolved CORS headers to send in response
+ */
+export interface CorsHeaders {
+    "Access-Control-Allow-Origin"?: string;
+    "Access-Control-Allow-Methods"?: string;
+    "Access-Control-Allow-Headers"?: string;
+    "Access-Control-Allow-Credentials"?: string;
+    "Access-Control-Expose-Headers"?: string;
+    "Access-Control-Max-Age"?: string;
+}
+/**
+ * JSON:API-style success response envelope
+ */
+export interface DataResponse<T = unknown> {
+    data: T;
+}
+/**
+ * JSON:API-style error object
+ */
+export interface ErrorObject {
+    status: number;
+    title: string;
+    detail?: string;
+}
+/**
+ * JSON:API-style error response envelope
+ */
+export interface ErrorResponse {
+    errors: ErrorObject[];
+}
+/**
+ * HTTP service configuration - extends base ServiceConfig with HTTP-specific options
+ */
+export interface FabricHttpConfig<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput = unknown, TAuth = unknown> extends Omit<ServiceConfig<TInput, TOutput>, "service"> {
+    /** Pre-built fabricService or inline service function */
+    service?: Service<TInput, TOutput> | ServiceConfig<TInput, TOutput>["service"];
+    /** Transform HTTP context to service input (defaults to body + query merge) */
+    http?: HttpTransformFunction<TInput>;
+    /** Authorization function or false for public endpoints */
+    authorization?: AuthorizationConfig<TAuth>;
+    /** CORS configuration (enabled by default) */
+    cors?: CorsOption;
+    /** Streaming configuration (disabled by default) */
+    stream?: StreamOption;
+}
+/**
+ * HTTP service - fabricService with HTTP-specific metadata
+ */
+export interface FabricHttpService<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput = unknown, TAuth = unknown> extends Service<TInput, TOutput> {
+    /** HTTP transformation function */
+    http: HttpTransformFunction<TInput>;
+    /** Authorization configuration */
+    authorization: AuthorizationConfig<TAuth>;
+    /** CORS configuration */
+    cors: CorsOption;
+    /** Streaming configuration */
+    stream: StreamOption;
+}
+/**
+ * Supported HTTP methods
+ */
+export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS";
+/**
+ * Default HTTP methods for fabric services
+ */
+export declare const DEFAULT_HTTP_METHODS: HttpMethod[];
+/**
+ * HTTP stream event types for SSE/NDJSON streaming
+ */
+export declare enum HttpStreamEventType {
+    /** Stream complete */
+    Complete = "complete",
+    /** Final response data */
+    Data = "data",
+    /** Error event */
+    Error = "error",
+    /** Fabric progress message (from sendMessage) */
+    Message = "message",
+    /** Keep-alive signal (no content) */
+    Noop = "noop",
+    /** LLM text chunk */
+    Text = "text",
+    /** LLM tool call event */
+    ToolCall = "tool_call",
+    /** LLM tool result event */
+    ToolResult = "tool_result"
+}
+/**
+ * Base stream event structure
+ */
+export interface HttpStreamEventBase {
+    stream: HttpStreamEventType;
+}
+/**
+ * Message event - progress updates from sendMessage
+ */
+export interface HttpStreamEventMessage extends HttpStreamEventBase {
+    stream: HttpStreamEventType.Message;
+    content: string;
+    level?: "trace" | "debug" | "info" | "warn" | "error";
+}
+/**
+ * Text event - LLM text chunk
+ */
+export interface HttpStreamEventText extends HttpStreamEventBase {
+    stream: HttpStreamEventType.Text;
+    content: string;
+}
+/**
+ * Tool call event - LLM requesting tool execution
+ */
+export interface HttpStreamEventToolCall extends HttpStreamEventBase {
+    stream: HttpStreamEventType.ToolCall;
+    toolCall: {
+        id: string;
+        name: string;
+        arguments: string;
+    };
+}
+/**
+ * Tool result event - result from tool execution
+ */
+export interface HttpStreamEventToolResult extends HttpStreamEventBase {
+    stream: HttpStreamEventType.ToolResult;
+    toolResult: {
+        id: string;
+        name: string;
+        result: unknown;
+    };
+}
+/**
+ * Data event - final response data
+ */
+export interface HttpStreamEventData<T = unknown> extends HttpStreamEventBase {
+    stream: HttpStreamEventType.Data;
+    data: T;
+}
+/**
+ * Error event
+ */
+export interface HttpStreamEventError extends HttpStreamEventBase {
+    stream: HttpStreamEventType.Error;
+    error: {
+        status: number | string;
+        title: string;
+        detail?: string;
+    };
+}
+/**
+ * Complete event - stream complete
+ */
+export interface HttpStreamEventComplete extends HttpStreamEventBase {
+    stream: HttpStreamEventType.Complete;
+}
+/**
+ * Noop event - keep-alive signal
+ */
+export interface HttpStreamEventNoop extends HttpStreamEventBase {
+    stream: HttpStreamEventType.Noop;
+}
+/**
+ * Union of all stream event types
+ */
+export type HttpStreamEvent = HttpStreamEventComplete | HttpStreamEventData | HttpStreamEventError | HttpStreamEventMessage | HttpStreamEventNoop | HttpStreamEventText | HttpStreamEventToolCall | HttpStreamEventToolResult;
+/**
+ * Stream configuration options (internal)
+ */
+export interface StreamConfig {
+    /** Output format - NDJSON (default) or SSE */
+    format?: "ndjson" | "sse";
+    /** Keep-alive heartbeat interval in ms (default: 15000) */
+    heartbeat?: number;
+    /** Include tool calls/results in stream (default: true) */
+    includeTools?: boolean;
+}
+/**
+ * Stream option - true to enable streaming, false to disable
+ */
+export type StreamOption = boolean;
+/**
+ * Streaming service function that yields events
+ */
+export type StreamingServiceFunction<TInput extends Record<string, unknown> = Record<string, unknown>> = (input: TInput, context: unknown) => AsyncIterable<HttpStreamEvent> | Promise<AsyncIterable<HttpStreamEvent>>;
+/**
+ * Route entry for FabricHttpServer - service with path and method configuration
+ */
+export interface FabricHttpServerRoute<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput = unknown, TAuth = unknown> {
+    /** The FabricHttpService to handle requests */
+    service: FabricHttpService<TInput, TOutput, TAuth>;
+    /** Route path pattern (defaults to /${alias}) */
+    path?: string;
+    /** Allowed HTTP methods (defaults to DEFAULT_HTTP_METHODS) */
+    methods?: HttpMethod[];
+}
+/**
+ * Service entry - either a FabricHttpService or a route config
+ */
+export type FabricHttpServerServiceEntry = FabricHttpService | FabricHttpServerRoute;
+/**
+ * Configuration for FabricHttpServer
+ */
+export interface FabricHttpServerConfig {
+    /** Array of services or route configs to register */
+    services: FabricHttpServerServiceEntry[];
+    /** Server-level authorization (applied to all services unless overridden) */
+    authorization?: AuthorizationConfig;
+    /** Server-level CORS config (applied to all services unless overridden) */
+    cors?: CorsOption;
+    /** Path prefix for all routes (e.g., "/api") */
+    prefix?: string;
+}
+/**
+ * API Gateway v1 (REST API) event format
+ */
+export interface ApiGatewayV1Event {
+    body: string | null;
+    headers: Record<string, string>;
+    httpMethod: string;
+    path: string;
+    pathParameters?: Record<string, string> | null;
+    queryStringParameters?: Record<string, string> | null;
+    requestContext?: {
+        requestId?: string;
+    };
+}
+/**
+ * API Gateway v2 (HTTP API) event format
+ */
+export interface ApiGatewayV2Event {
+    body?: string;
+    headers: Record<string, string>;
+    rawPath: string;
+    rawQueryString?: string;
+    requestContext: {
+        http: {
+            method: string;
+            path: string;
+        };
+        requestId?: string;
+    };
+    pathParameters?: Record<string, string>;
+    queryStringParameters?: Record<string, string>;
+}
+/**
+ * Union of API Gateway event types
+ */
+export type ApiGatewayEvent = ApiGatewayV1Event | ApiGatewayV2Event;
+/**
+ * API Gateway response format (compatible with v1 and v2)
+ */
+export interface ApiGatewayResponse {
+    statusCode: number;
+    headers: Record<string, string>;
+    body: string;
+}
+/**
+ * Registered route with resolved path and methods
+ */
+export interface RegisteredRoute {
+    /** Compiled path pattern */
+    path: string;
+    /** Path segments for matching */
+    segments: string[];
+    /** Allowed methods */
+    methods: HttpMethod[];
+    /** The service to handle requests */
+    service: FabricHttpService;
+}
+/**
+ * Match result from route matching
+ */
+export interface RouteMatch {
+    /** The matched route */
+    route: RegisteredRoute;
+    /** Extracted path parameters */
+    params: Record<string, string>;
+}
+/**
+ * FabricHttpServer handler function
+ */
+export type FabricHttpServerHandler = (event: ApiGatewayEvent) => Promise<ApiGatewayResponse>;
+/**
+ * FabricHttpServer with metadata
+ */
+export interface FabricHttpServer extends FabricHttpServerHandler {
+    /** Registered services */
+    services: FabricHttpService[];
+    /** Route prefix */
+    prefix?: string;
+    /** Registered routes */
+    routes: RegisteredRoute[];
+}

package/dist/cjs/index/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Index Module for @jaypie/fabric
+ *
+ * Exports all index-related types, functions, and constants.
+ */
+export { ARCHIVED_SUFFIX, DEFAULT_INDEXES, DEFAULT_SORT_KEY, DELETED_SUFFIX, type IndexDefinition, type IndexField, type ModelSchema, } from "./types.js";
+export { buildCompositeKey, calculateIndexSuffix, calculateScope, generateIndexName, type IndexableModel, populateIndexKeys, tryBuildCompositeKey, } from "./keyBuilder.js";
+export { clearRegistry, getAllRegisteredIndexes, getModelIndexes, getModelSchema, getRegisteredModels, isModelRegistered, registerModel, } from "./registry.js";

package/dist/cjs/index/keyBuilder.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Key Builder for @jaypie/fabric
+ *
+ * Builds composite keys from model fields and index definitions.
+ */
+import { type IndexDefinition, type IndexField } from "./types.js";
+/**
+ * Model with fields for indexing.
+ *
+ * Does not extend FabricModel to allow flexibility with timestamp types
+ * (DynamoDB uses string timestamps, FabricModel uses Date objects).
+ */
+export interface IndexableModel {
+    /** Schema reference (required for indexing) */
+    model: string;
+    /** Scope (optional) */
+    scope?: string;
+    /** Chronological ordering timestamp (optional) */
+    sequence?: number;
+    /** Archived timestamp - presence triggers #archived suffix */
+    archivedAt?: Date | string | null;
+    /** Deleted timestamp - presence triggers #deleted suffix */
+    deletedAt?: Date | string | null;
+    /** Allow any additional fields */
+    [key: string]: unknown;
+}
+/**
+ * Build a composite key from model fields
+ *
+ * @param model - Model with fields to extract
+ * @param fields - Field names to combine
+ * @param suffix - Optional suffix to append (e.g., "#deleted")
+ * @returns Composite key string (e.g., "@#record#my-alias")
+ * @throws ConfigurationError if a required field is missing
+ */
+export declare function buildCompositeKey(model: IndexableModel, fields: IndexField[], suffix?: string): string;
+/**
+ * Try to build a composite key, returning undefined if fields are missing
+ *
+ * @param model - Model with fields to extract
+ * @param fields - Field names to combine
+ * @param suffix - Optional suffix to append
+ * @returns Composite key string or undefined if fields missing
+ */
+export declare function tryBuildCompositeKey(model: IndexableModel, fields: IndexField[], suffix?: string): string | undefined;
+/**
+ * Generate an index name from partition key fields
+ *
+ * @param pk - Partition key field names
+ * @returns Generated index name (e.g., "indexOuModelAlias")
+ */
+export declare function generateIndexName(pk: IndexField[]): string;
+/**
+ * Calculate the suffix for index keys based on model state
+ *
+ * @param model - Model to check for archived/deleted state
+ * @returns Suffix string (e.g., "", "#archived", "#deleted", "#archived#deleted")
+ */
+export declare function calculateIndexSuffix(model: IndexableModel): string;
+/**
+ * Populate index keys on a model based on index definitions
+ *
+ * Only the partition key composite is stored on the model (e.g., indexOu).
+ * The sort key (e.g., sequence) is a regular field that the GSI references directly.
+ *
+ * @param model - Model to populate index keys on
+ * @param indexes - Index definitions to use
+ * @param suffix - Optional suffix to append to all index keys
+ * @returns Model with index keys populated
+ */
+export declare function populateIndexKeys<T extends IndexableModel>(model: T, indexes: IndexDefinition[], suffix?: string): T;
+/**
+ * Calculate scope from parent reference
+ *
+ * @param parent - Parent model with model and id
+ * @returns Scope string ("{parent.model}#{parent.id}") or APEX ("@") if no parent
+ */
+export declare function calculateScope(parent?: {
+    id: string;
+    model: string;
+}): string;

package/dist/cjs/index/registry.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Model Registry for @jaypie/fabric
+ *
+ * Stores model schemas with their index definitions.
+ * DynamoDB reads from this registry to create GSIs and select indexes for queries.
+ */
+import { type IndexDefinition, type ModelSchema } from "./types.js";
+/**
+ * Register a model schema with its index definitions
+ *
+ * @param schema - Model schema with model name and optional indexes
+ */
+export declare function registerModel(schema: ModelSchema): void;
+/**
+ * Get a model schema by name
+ *
+ * @param model - Model name to look up
+ * @returns Model schema or undefined if not registered
+ */
+export declare function getModelSchema(model: string): ModelSchema | undefined;
+/**
+ * Get index definitions for a model
+ *
+ * Returns the model's custom indexes if registered,
+ * otherwise returns DEFAULT_INDEXES.
+ *
+ * @param model - Model name to get indexes for
+ * @returns Array of index definitions
+ */
+export declare function getModelIndexes(model: string): IndexDefinition[];
+/**
+ * Get all registered models
+ *
+ * @returns Array of model names
+ */
+export declare function getRegisteredModels(): string[];
+/**
+ * Get all unique indexes across all registered models
+ *
+ * Used by createTable to collect all GSIs that need to be created.
+ * Deduplicates by index name.
+ *
+ * @returns Array of unique index definitions
+ */
+export declare function getAllRegisteredIndexes(): IndexDefinition[];
+/**
+ * Check if a model is registered
+ *
+ * @param model - Model name to check
+ * @returns true if model is registered
+ */
+export declare function isModelRegistered(model: string): boolean;
+/**
+ * Clear the model registry (for testing)
+ */
+export declare function clearRegistry(): void;

package/dist/cjs/index/types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Index Types for @jaypie/fabric
+ *
+ * Declarative index definitions for DynamoDB single-table design.
+ * Models can specify their own indexes, and dynamodb will create
+ * GSIs and auto-detect which index to use for queries.
+ */
+import type { FabricModel } from "../models/base.js";
+/**
+ * Index field - can be a FabricModel field name or custom field
+ */
+export type IndexField = keyof FabricModel | string;
+/**
+ * Single index definition
+ *
+ * pk fields are combined with SEPARATOR to form the partition key.
+ * sk fields are combined with SEPARATOR to form the sort key.
+ */
+export interface IndexDefinition {
+    /** Name of the index (auto-generated from pk fields if not provided) */
+    name?: string;
+    /** Partition key fields - combined with SEPARATOR */
+    pk: IndexField[];
+    /** Sort key fields - combined with SEPARATOR (default: ["sequence"]) */
+    sk?: IndexField[];
+    /** Only create index key when ALL pk fields are present on model */
+    sparse?: boolean;
+}
+/**
+ * Model schema with index definitions
+ */
+export interface ModelSchema {
+    /** The model name (e.g., "record", "message", "chat") */
+    model: string;
+    /** Custom indexes for this model (uses DEFAULT_INDEXES if not specified) */
+    indexes?: IndexDefinition[];
+}
+/**
+ * Default indexes for the DynamoDB GSI pattern.
+ * These are used when a model does not specify custom indexes.
+ */
+export declare const DEFAULT_INDEXES: IndexDefinition[];
+/**
+ * Default sort key fields when sk is not specified
+ */
+export declare const DEFAULT_SORT_KEY: IndexField[];
+/**
+ * Suffix appended to index keys when model is archived
+ */
+export declare const ARCHIVED_SUFFIX = "#archived";
+/**
+ * Suffix appended to index keys when model is deleted
+ */
+export declare const DELETED_SUFFIX = "#deleted";