@nilejs/nile 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,646 @@
+import { Context, Hono } from 'hono';
+import { Result, ErrType, ResultMethods } from 'slang-ts';
+import { Store } from 'hono-rate-limiter';
+import z, { ZodTypeAny } from 'zod';
+
+/**
+ * CORS options compatible with Hono's cors middleware
+ */
+interface CorsOptions {
+    /**
+     * The value of "Access-Control-Allow-Origin" CORS header.
+     * Can be a string, array of strings, or a function that returns the allowed origin.
+     */
+    origin?: string | string[] | ((origin: string, c: Context) => string | undefined | null);
+    /**
+     * The value of "Access-Control-Allow-Methods" CORS header.
+     * Can be an array of HTTP methods or a function that returns allowed methods.
+     */
+    allowMethods?: string[] | ((origin: string, c: Context) => string[]);
+    /**
+     * The value of "Access-Control-Allow-Headers" CORS header.
+     */
+    allowHeaders?: string[];
+    /**
+     * The value of "Access-Control-Max-Age" CORS header.
+     */
+    maxAge?: number;
+    /**
+     * The value of "Access-Control-Allow-Credentials" CORS header.
+     */
+    credentials?: boolean;
+    /**
+     * The value of "Access-Control-Expose-Headers" CORS header.
+     */
+    exposeHeaders?: string[];
+}
+/**
+ * CORS resolver function that determines CORS behavior per request
+ * - Return `true` to allow the origin with default options
+ * - Return `false` to reject the request
+ * - Return a CorsOptions object to override options for this request
+ */
+type CorsResolver = (origin: string, c: Context) => boolean | CorsOptions | undefined;
+/**
+ * Per-route CORS configuration
+ */
+interface CorsRouteRule {
+    /**
+     * Path pattern to match (e.g., '/api/*', '/uploads/*')
+     */
+    path: string;
+    /**
+     * Static CORS options for this route
+     */
+    options?: CorsOptions;
+    /**
+     * Dynamic resolver function to determine CORS behavior per request
+     */
+    resolver?: CorsResolver;
+}
+/**
+ * Main CORS configuration for the REST server
+ */
+interface CorsConfig {
+    /**
+     * Enable or disable CORS
+     * - `true` or `'default'`: Use default CORS configuration
+     * - `false`: Disable CORS middleware entirely (no CORS headers are set)
+     */
+    enabled?: boolean | "default";
+    /**
+     * Default CORS options applied globally
+     */
+    defaults?: CorsOptions;
+    /**
+     * Additional route-specific CORS rules
+     */
+    addCors?: CorsRouteRule[];
+}
+
+interface RateLimitConfig {
+    windowMs?: number;
+    limit?: number;
+    standardHeaders?: boolean;
+    limitingHeader: string;
+    store?: Store;
+    diagnostics?: boolean;
+}
+interface RestConfig {
+    baseUrl: string;
+    host?: string;
+    port?: number;
+    diagnostics?: boolean;
+    enableStatic?: boolean;
+    enableStatus?: boolean;
+    rateLimiting?: RateLimitConfig;
+    allowedOrigins: string[];
+    cors?: CorsConfig;
+    uploads?: {
+        enforceContentType?: boolean;
+        limits?: {
+            maxFiles?: number;
+            maxFileSize?: number;
+            minFileSize?: number;
+            maxTotalSize?: number;
+            maxFilenameLength?: number;
+        };
+        allow?: {
+            mimeTypes?: string[];
+            extensions?: string[];
+        };
+        diagnostics?: boolean;
+    };
+}
+
+interface WebSocketContext {
+    connection: unknown;
+    headers?: Record<string, string>;
+    cookies?: Record<string, string>;
+    [key: string]: unknown;
+}
+interface RPCContext {
+    [key: string]: unknown;
+}
+interface BaseContext {
+    rest?: Context;
+    ws?: WebSocketContext;
+    rpc?: RPCContext;
+}
+interface Sessions {
+    rest?: Record<string, unknown>;
+    ws?: Record<string, unknown>;
+    rpc?: Record<string, unknown>;
+}
+interface Sessions {
+    rest?: Record<string, unknown>;
+    ws?: Record<string, unknown>;
+    rpc?: Record<string, unknown>;
+}
+interface NileLogger {
+    info: (input: {
+        atFunction: string;
+        message: string;
+        data?: unknown;
+    }) => string;
+    warn: (input: {
+        atFunction: string;
+        message: string;
+        data?: unknown;
+    }) => string;
+    error: (input: {
+        atFunction: string;
+        message: string;
+        data?: unknown;
+    }) => string;
+}
+interface Resources<TDB = unknown> {
+    logger?: NileLogger;
+    database?: TDB;
+    cache?: unknown;
+    [key: string]: unknown;
+}
+interface NileContext<TDB = unknown> {
+    readonly rest?: Context;
+    readonly ws?: WebSocketContext;
+    readonly rpc?: RPCContext;
+    sessions: Sessions;
+    readonly _store: Readonly<Map<string, unknown>>;
+    readonly get: <T = unknown>(key: string) => T | undefined;
+    readonly set: <T = unknown>(key: string, value: T) => void;
+    readonly resources?: Resources<TDB>;
+    /** Retrieve session data for a specific interface */
+    getSession: (name: keyof Sessions) => Record<string, unknown> | undefined;
+    /** Store session data for a specific interface */
+    setSession: (name: keyof Sessions, data: Record<string, unknown>) => void;
+    hookContext: HookContext;
+    updateHookState: (key: string, value: unknown) => void;
+    addHookLog: (phase: "before" | "after", logEntry: {
+        name: string;
+        input: unknown;
+        output: unknown;
+        passed: boolean;
+    }) => void;
+    setHookError: (error: string) => void;
+    setHookOutput: (output: unknown) => void;
+    resetHookContext: (actionName: string, input: unknown) => void;
+}
+type BeforeActionHandler<T, E> = (params: {
+    nileContext: NileContext<unknown>;
+    action: Action;
+    payload: unknown;
+}) => Result<T, E>;
+type AfterActionHandler<T, E> = (params: {
+    nileContext: NileContext<unknown>;
+    action: Action;
+    payload: unknown;
+    result: Result<T, E>;
+}) => Result<T, E>;
+type ServerRuntime = "bun" | "node";
+interface ServerConfig {
+    serverName: string;
+    runtime?: ServerRuntime;
+    services: Services;
+    diagnostics?: boolean;
+    /** Print registered services table to console on boot (default: true) */
+    logServices?: boolean;
+    resources?: Resources<unknown>;
+    rest?: RestConfig;
+    websocket?: Record<string, unknown>;
+    rpc?: Record<string, unknown>;
+    onBeforeActionHandler?: BeforeActionHandler<unknown, unknown>;
+    onAfterActionHandler?: AfterActionHandler<unknown, unknown>;
+    onBoot?: {
+        fn: (context: NileContext<unknown>) => Promise<void> | void;
+    };
+}
+interface ExternalResponse {
+    status: boolean;
+    message: string;
+    data: Record<string, unknown>;
+}
+interface ExternalRequest {
+    intent: "explore" | "execute" | "schema";
+    service: string;
+    action: string;
+    payload: Record<string, unknown>;
+}
+interface NileServer {
+    config: ServerConfig;
+    engine: Engine;
+    context: NileContext<unknown>;
+    rest?: {
+        app: Hono;
+        config: RestConfig;
+    };
+}
+
+interface HookDefinition {
+    service: string;
+    action: string;
+    /** When true, hook failure stops the pipeline. Non-critical hooks log errors but continue. */
+    isCritical: boolean;
+}
+interface ActionResultConfig {
+    pipeline: boolean;
+}
+interface HookLogEntry {
+    name: string;
+    input: unknown;
+    output: unknown;
+    passed: boolean;
+}
+interface HookContext {
+    actionName: string;
+    input: unknown;
+    output?: unknown;
+    error?: string;
+    state: Record<string, unknown>;
+    log: {
+        before: HookLogEntry[];
+        after: HookLogEntry[];
+    };
+}
+type ActionHandler<T = unknown, E = string> = (data: Record<string, unknown>, context?: NileContext<unknown>) => Result<T, E> | Promise<Result<T, E>>;
+interface Action {
+    name: string;
+    description: string;
+    isProtected?: boolean;
+    visibility?: {
+        rest?: boolean;
+        rpc?: boolean;
+    };
+    isSpecial?: {
+        contentType: "multipart/form-data" | "application/json" | "other";
+        uploadMode?: "flat" | "structured";
+    };
+    handler: ActionHandler;
+    validation?: z.ZodTypeAny | null;
+    hooks?: {
+        before?: HookDefinition[];
+        after?: HookDefinition[];
+    };
+    result?: ActionResultConfig;
+    accessControl?: string[];
+    meta?: Record<string, unknown>;
+}
+type Actions = Action[];
+interface Service {
+    name: string;
+    description: string;
+    actions: Actions;
+    meta?: Record<string, unknown>;
+}
+type Services = Service[];
+interface ServiceSummary {
+    name: string;
+    description: string;
+    meta?: Record<string, unknown>;
+    actions: string[];
+}
+interface ActionSummary {
+    name: string;
+    description: string;
+    isProtected: boolean;
+    validation: boolean;
+    accessControl: string[];
+}
+interface EngineOptions {
+    diagnostics?: boolean;
+    /** Optional logger from resources — used for diagnostics output when available */
+    logger?: {
+        info: (msg: string, data?: unknown) => void;
+    } | NileLogger;
+    services: Services;
+    onBeforeActionHandler?: BeforeActionHandler<unknown, unknown>;
+    onAfterActionHandler?: AfterActionHandler<unknown, unknown>;
+}
+/** Formalized return type of createEngine */
+interface Engine {
+    getServices: () => Result<ServiceSummary[], string>;
+    getServiceActions: (serviceName: string) => Result<ActionSummary[], string>;
+    getAction: (serviceName: string, actionName: string) => Result<Action, string>;
+    executeAction: (serviceName: string, actionName: string, payload: unknown, nileContext: NileContext<unknown>) => Promise<Result<unknown, string>>;
+}
+
+/**
+ * Typed identity for defining a single action with full type inference.
+ * No runtime overhead — returns the config object as-is.
+ */
+declare function createAction(config: Action): Action;
+/**
+ * Typed identity for defining multiple actions with full type inference.
+ * No runtime overhead — returns the config array as-is.
+ */
+declare function createActions(configs: Action[]): Action[];
+
+/**
+ * Typed identity for defining a service with full type inference.
+ * No runtime overhead — returns the config object as-is.
+ */
+declare function createService(config: Service): Service;
+/**
+ * Typed identity for defining multiple services with full type inference.
+ * No runtime overhead — returns the config array as-is.
+ */
+declare function createServices(configs: Service[]): Service[];
+
+interface Log {
+    atFunction: string;
+    appName: string;
+    message: string;
+    data?: unknown;
+    level?: "info" | "warn" | "error";
+    log_id?: string;
+}
+/** Configuration for log file chunking behavior */
+interface LoggerConfig {
+    /** Time-based chunking strategy. Default: 'none' (single file per app) */
+    chunking?: "monthly" | "daily" | "weekly" | "none";
+}
+/**
+ * Creates a new log entry with the provided log information.
+ * Supports optional chunking config to split logs into time-based files.
+ * @param log - The log object containing the log details
+ * @param config - Optional logger config for chunking behavior
+ * @returns The generated log ID (or JSON string in agentic mode)
+ * @throws {Error} If appName is missing in the log object
+ */
+declare const createLog: (log: Log, config?: LoggerConfig) => string;
+interface LogFilter {
+    appName?: string;
+    log_id?: string;
+    level?: "info" | "warn" | "error";
+    from?: Date;
+    to?: Date;
+}
+/**
+ * Retrieves logs based on the provided filters.
+ * Supports reading from chunked files when a LoggerConfig with chunking is provided.
+ * When chunking is enabled, uses from/to date filters to intelligently select
+ * only the relevant chunk files instead of scanning all files.
+ * @param filters - Optional filters to apply when retrieving logs
+ * @param config - Optional logger config matching the chunking used when writing
+ * @returns An array of log entries matching the filters
+ */
+declare const getLogs: (filters?: LogFilter, config?: LoggerConfig) => Log[];
+
+type LogInput = Omit<Log, "appName">;
+/**
+ * Creates a logger instance bound to a specific app name.
+ * Optionally accepts a LoggerConfig for time-based file chunking.
+ * @param appName - The application name (determines log file/directory)
+ * @param config - Optional config for chunking (monthly, daily, weekly)
+ */
+declare const createLogger: (appName: string, config?: LoggerConfig) => {
+    info: (input: LogInput) => string;
+    warn: (input: LogInput) => string;
+    error: (input: LogInput) => string;
+};
+
+/**
+ * Retrieves the runtime NileContext.
+ *
+ * Use this to access shared resources (database, logger) and context storage
+ * from anywhere in your application. Supports a TDB generic to provide
+ * end-to-end type safety for your database instance.
+ *
+ * @template TDB - The type of your database instance (e.g. typeof db)
+ * @returns The active NileContext<TDB>
+ * @throws If called before createNileServer has initialized the global context.
+ */
+declare function getContext<TDB = unknown>(): NileContext<TDB>;
+/**
+ * Bootstraps a Nile server instance.
+ *
+ * Wires together the Action Engine, shared NileContext, and interface layers (REST).
+ * This is the primary entry point for a Nile application. It handles service
+ * registration, resource attachment, and server lifecycle.
+ *
+ * @param config - Server configuration including services, rest options, and resources
+ * @returns A NileServer instance containing the engine and (optional) REST app
+ */
+declare function createNileServer(config: ServerConfig): NileServer;
+
+/**
+ * Database instance or transaction pointer type.
+ * Accepts a root DB instance (with .transaction method) or a transaction pointer.
+ *
+ * @example
+ * ```typescript
+ * type DBX = typeof db | Parameters<Parameters<typeof db.transaction>[0]>[0];
+ * ```
+ */
+type DBX<TDB> = TDB extends {
+    transaction: (fn: (tx: infer TX) => unknown) => unknown;
+} ? TDB | TX : TDB;
+/**
+ * Standard params interface for functions that can optionally use a transaction.
+ *
+ * @example
+ * ```typescript
+ * const createCompany = async ({ company, dbx }: DBParams<typeof db> & { company: NewCompany }) => { ... }
+ * ```
+ */
+interface DBParams<TDB> {
+    dbx?: DBX<TDB>;
+}
+/**
+ * Zod schemas generated from a Drizzle table.
+ */
+interface TableSchemas<_TTable> {
+    insert: ZodTypeAny;
+    update: ZodTypeAny;
+    select: ZodTypeAny;
+}
+/**
+ * Configuration for the createModel factory.
+ *
+ * @property db - Explicit database instance. When omitted, resolved from Nile context at call time.
+ * @property name - Human-readable entity name for error messages (e.g. "task", "user").
+ * @property cursorColumn - Default column name for cursor-based pagination. Defaults to "id".
+ */
+interface ModelOptions<TDB = unknown> {
+    db?: TDB;
+    name: string;
+    cursorColumn?: string;
+}
+/** Params for model methods that support transactions */
+interface ModelWriteParams<TInsert, TDB> {
+    data: TInsert;
+    dbx?: DBX<TDB>;
+}
+/** Params for model update methods */
+interface ModelUpdateParams<TSelect, TDB> {
+    id: string;
+    data: Partial<TSelect>;
+    dbx?: DBX<TDB>;
+}
+/** Offset-based pagination result */
+interface OffsetPage<T> {
+    items: T[];
+    total: number;
+    hasMore: boolean;
+}
+/** Cursor-based pagination result */
+interface CursorPage<T> {
+    items: T[];
+    nextCursor: string | null;
+    hasMore: boolean;
+}
+/** Offset pagination options */
+interface OffsetPaginationOptions {
+    limit?: number;
+    offset?: number;
+    cursor?: never;
+    cursorColumn?: never;
+}
+/** Cursor pagination options — value is the cursor, column overrides model default */
+interface CursorPaginationOptions {
+    limit?: number;
+    cursor: string;
+    cursorColumn?: string;
+    offset?: never;
+}
+type PaginationOptions = OffsetPaginationOptions | CursorPaginationOptions;
+/** All CRUD operations returned by createModel */
+interface ModelOperations<TSelect, TInsert, TDB> {
+    /** Insert a new record with auto-validation */
+    create(params: ModelWriteParams<TInsert, TDB>): Promise<Result<TSelect, string>>;
+    /** Insert a new record wrapped in a transaction */
+    createTx(params: ModelWriteParams<TInsert, TDB>): Promise<Result<TSelect, string>>;
+    /** Find a single record by UUID */
+    findById(id: string): Promise<Result<TSelect, string>>;
+    /** Update a record by UUID with auto-validation */
+    update(params: ModelUpdateParams<TSelect, TDB>): Promise<Result<TSelect, string>>;
+    /** Update a record wrapped in a transaction */
+    updateTx(params: ModelUpdateParams<TSelect, TDB>): Promise<Result<TSelect, string>>;
+    /** Delete a record by UUID, returns the deleted row */
+    delete(id: string): Promise<Result<TSelect, string>>;
+    /** Get all records ordered by newest first (when created_at/createdAt exists) */
+    findAll(): Promise<Result<TSelect[], string>>;
+    /** Paginated query — offset-based when offset is set, cursor-based when cursor is set */
+    findPaginated(options?: OffsetPaginationOptions): Promise<Result<OffsetPage<TSelect>, string>>;
+    findPaginated(options: CursorPaginationOptions): Promise<Result<CursorPage<TSelect>, string>>;
+    findPaginated(options?: PaginationOptions): Promise<Result<OffsetPage<TSelect> | CursorPage<TSelect>, string>>;
+    /** The underlying Drizzle table — escape hatch for custom queries */
+    table: unknown;
+    /** Auto-generated Zod schemas for insert/update/select validation */
+    schemas: TableSchemas<unknown>;
+}
+
+/**
+ * Creates a CRUD model for a Drizzle table, eliminating repetitive boilerplate.
+ *
+ * All methods return `Result<T, string>` — `Ok(data)` on success, `Err(message)` on failure.
+ * Validation, error handling, and transaction variants are built in.
+ *
+ * For anything beyond basic CRUD, use the exposed `table` and `schemas` properties
+ * to compose custom queries with Drizzle directly.
+ *
+ * @param table - Drizzle table definition (from pgTable, sqliteTable, etc.)
+ * @param options - Configuration: entity name, optional db instance, cursor column
+ * @returns Object with CRUD operations, plus escape hatches (table, schemas)
+ *
+ * @example
+ * ```typescript
+ * import { createModel } from "@nilejs/nile";
+ * import { tasks } from "./schema";
+ * import { db } from "./client";
+ *
+ * // Explicit db
+ * export const taskModel = createModel(tasks, { db, name: "task" });
+ *
+ * // Context-resolved db (resolved at call time)
+ * export const taskModel = createModel(tasks, { name: "task" });
+ *
+ * // Usage
+ * const result = await taskModel.create({ data: { title: "Ship it" } });
+ * const task = await taskModel.findById("uuid-123");
+ * const page = await taskModel.findPaginated({ limit: 20, offset: 0 });
+ * ```
+ */
+declare function createModel<TTable extends {
+    $inferSelect: unknown;
+    $inferInsert: unknown;
+}, TDB = unknown>(table: TTable, options: ModelOptions<TDB>): ModelOperations<TTable["$inferSelect"], TTable["$inferInsert"], TDB>;
+
+/**
+ * Creates a transaction-aware variant of a database function.
+ * Expects the wrapped function to accept a single object parameter with optional dbx field.
+ *
+ * When dbx is root db (has .transaction method):
+ * - Creates new transaction and executes function inside it
+ * - On Result.isError, throws Error to trigger automatic rollback
+ * - Returns successful result or throws
+ *
+ * When dbx is tx pointer (no .transaction method):
+ * - Executes function directly within existing transaction scope
+ * - On Result.isError, throws Error to trigger parent transaction rollback
+ * - Returns successful result or throws
+ *
+ * Both cases ensure database rollback on any error by throwing.
+ *
+ * @example
+ * ```typescript
+ * const createCompanyTx = createTransactionVariant(createCompany);
+ * // Type-safe: requires all params from createCompany
+ * const result = await createCompanyTx({ company: {...}, dbx: tx });
+ * ```
+ */
+declare function createTransactionVariant<TParams extends DBParams<TDB>, TData, TDB = unknown>(fn: (params: TParams) => Promise<Result<TData, unknown>>): (params: TParams) => Promise<Result<TData, unknown>>;
+
+/**
+ * Generates Zod schemas (insert, update, select) from a Drizzle table.
+ *
+ * @param table - The Drizzle table definition
+ * @returns Object containing insert, update, and select Zod schemas
+ *
+ * @example
+ * ```typescript
+ * import { getZodSchema } from '@nilejs/nile';
+ * import { companies } from './schema';
+ *
+ * const schemas = getZodSchema(companies);
+ * const insert = schemas.insert.parse(data);
+ * const update = schemas.update.partial().parse(data);
+ * ```
+ */
+declare function getZodSchema<TTable extends object>(table: TTable): TableSchemas<TTable>;
+
+/**
+ * Parameters for the handleError utility.
+ *
+ * @property message - Human-readable error description, included in the returned Result error string
+ * @property data - Optional structured data logged alongside the error for debugging
+ * @property logger - Explicit logger instance; when omitted, resolves from the current Nile request context
+ * @property atFunction - Name of the calling function for log attribution; auto-inferred from stack trace when omitted
+ */
+interface HandleErrorParams {
+    message: string;
+    data?: unknown;
+    logger?: NileLogger;
+    atFunction?: string;
+}
+/**
+ * Logs an error via the resolved logger and returns a typed Err result.
+ * Resolves the logger from the current Nile request context when not provided explicitly.
+ * The returned error string includes the log ID for traceability: `[logId] message`.
+ *
+ * @param params - Error details including message, optional data, logger, and caller function name
+ * @returns Always an Err variant — `ErrType<string> & ResultMethods<never>`, compatible with any `Result<T, E>` union
+ *
+ * @example
+ * ```typescript
+ * if (!user) {
+ *   return handleError({
+ *     message: "User not found",
+ *     data: { userId },
+ *     atFunction: "getUserById",
+ *   });
+ * }
+ * ```
+ */
+declare function handleError(params: HandleErrorParams): ErrType<string> & ResultMethods<never>;
+
+export { type Action, type ActionHandler, type ActionResultConfig, type ActionSummary, type Actions, type AfterActionHandler, type BaseContext, type BeforeActionHandler, type CorsConfig, type CorsOptions, type CorsResolver, type CorsRouteRule, type CursorPage, type CursorPaginationOptions, type DBParams, type DBX, type Engine, type EngineOptions, type ExternalRequest, type ExternalResponse, type HookContext, type HookDefinition, type HookLogEntry, type Log, type LogFilter, type LoggerConfig, type ModelOperations, type ModelOptions, type NileContext, type NileLogger, type NileServer, type OffsetPage, type OffsetPaginationOptions, type RPCContext, type RateLimitConfig, type Resources, type RestConfig, type ServerConfig, type ServerRuntime, type Service, type ServiceSummary, type Services, type Sessions, type WebSocketContext, createAction, createActions, createLog, createLogger, createModel, createNileServer, createService, createServices, createTransactionVariant, getContext, getLogs, getZodSchema, handleError };