@kuratchi/js 0.0.2 → 0.0.4

package/dist/runtime/do.js

@@ -13,6 +13,21 @@
  * User code never touches these — they're wired up from kuratchi.config.ts.
  */
 // ── Internal: stub resolver registry ────────────────────────
+let __doSelf = null;
+/** @internal — called by compiler-generated method wrappers */
+export function __setDoContext(self) {
+    __doSelf = self;
+}
+/** Get the DO's ORM database instance */
+export function getDb() {
+    if (!__doSelf)
+        throw new Error('getDb() called outside of a DO context');
+    return __doSelf.db;
+}
+/** @internal — read by context.ts getCtx()/getEnv() */
+export function __getDoSelf() {
+    return __doSelf;
+}
 const _resolvers = new Map();
 const _classBindings = new WeakMap();
 /** @internal — called by compiler-generated init code */

package/dist/runtime/index.d.ts

@@ -1,8 +1,9 @@
 export { createApp } from './app.js';
 export { defineConfig } from './config.js';
+export { defineRuntime } from './runtime.js';
 export { Router, filePathToPattern } from './router.js';
 export { getCtx, getRequest, getLocals, getParams, getParam, redirect, goto, setBreadcrumbs, getBreadcrumbs, breadcrumbsHome, breadcrumbsPrev, breadcrumbsNext, breadcrumbsCurrent, buildDefaultBreadcrumbs, } from './context.js';
 export { kuratchiDO, doRpc } from './do.js';
 export { extractSubdomainSlug, extractSlugFromPrefix, matchContainerViewPath, rewriteProxyLocationHeader, buildContainerRequest, createContainerEnvVars, startContainer, proxyToContainer, handleContainerRouting, forwardJsonPostToContainerDO, matchSiteViewPath, buildSiteContainerRequest, createWpContainerEnvVars, startSiteContainer, proxyToSiteContainer, } from './containers.js';
-export type { AppConfig, Env, AuthConfig, RouteContext, RouteModule, LayoutModule } from './types.js';
+export type { AppConfig, Env, AuthConfig, RouteContext, RouteModule, ApiRouteModule, HttpMethod, LayoutModule, RuntimeContext, RuntimeDefinition, RuntimeStep, RuntimeNext, RuntimeErrorResult, } from './types.js';
 export type { RpcOf } from './do.js';

package/dist/runtime/index.js

@@ -1,5 +1,6 @@
 export { createApp } from './app.js';
 export { defineConfig } from './config.js';
+export { defineRuntime } from './runtime.js';
 export { Router, filePathToPattern } from './router.js';
 export { getCtx, getRequest, getLocals, getParams, getParam, redirect, goto, setBreadcrumbs, getBreadcrumbs, breadcrumbsHome, breadcrumbsPrev, breadcrumbsNext, breadcrumbsCurrent, buildDefaultBreadcrumbs, } from './context.js';
 export { kuratchiDO, doRpc } from './do.js';

package/dist/runtime/page-error.d.ts

@@ -0,0 +1,16 @@
+/**
+ * PageError — throw from a route's load scope to return a specific HTTP status page.
+ *
+ * Without PageError, any thrown error becomes a 500. PageError lets you return
+ * the correct HTTP status (404, 403, 401, etc.) and an optional message.
+ *
+ * @example
+ * const post = await db.posts.findOne({ id: params.id });
+ * if (!post) throw new PageError(404);
+ * if (!post.isPublished) throw new PageError(403, 'This post is not published');
+ */
+export declare class PageError extends Error {
+    readonly isPageError = true;
+    readonly status: number;
+    constructor(status: number, message?: string);
+}

package/dist/runtime/page-error.js

@@ -0,0 +1,20 @@
+/**
+ * PageError — throw from a route's load scope to return a specific HTTP status page.
+ *
+ * Without PageError, any thrown error becomes a 500. PageError lets you return
+ * the correct HTTP status (404, 403, 401, etc.) and an optional message.
+ *
+ * @example
+ * const post = await db.posts.findOne({ id: params.id });
+ * if (!post) throw new PageError(404);
+ * if (!post.isPublished) throw new PageError(403, 'This post is not published');
+ */
+export class PageError extends Error {
+    isPageError = true;
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = 'PageError';
+        this.status = status;
+    }
+}

package/dist/runtime/runtime.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Runtime extension system
+ */
+import type { Env, RuntimeDefinition } from './types.js';
+export declare function defineRuntime<E extends Env = Env>(runtime: RuntimeDefinition<E>): RuntimeDefinition<E>;

package/dist/runtime/runtime.js

@@ -0,0 +1,6 @@
+/**
+ * Runtime extension system
+ */
+export function defineRuntime(runtime) {
+    return runtime;
+}

package/dist/runtime/types.d.ts

@@ -1,13 +1,13 @@
 /**
  * Core framework types
  */
-/** Cloudflare Worker env — consumers define their own Env type */
+/** Cloudflare Worker env â€" consumers define their own Env type */
 export type Env = Record<string, any>;
-/** Route context — passed to load functions, actions, and server utilities */
+/** Route context â€" passed to load functions, actions, and server utilities */
 export interface RouteContext<E extends Env = Env> {
     /** The incoming Request (standard Web API) */
     request: Request;
-    /** Cloudflare Worker env — D1, KV, R2, DO, AI, etc. */
+    /** Cloudflare Worker env â€" D1, KV, R2, DO, AI, etc. */
     env: E;
     /** Cloudflare execution context */
     ctx: ExecutionContext;
@@ -22,36 +22,47 @@ export interface RouteContext<E extends Env = Env> {
 export interface RouteModule {
     /** Pattern string (e.g., '/todos', '/blog/:slug') */
     pattern: string;
-    /** Load function — runs on GET, returns data for the template */
+    /** Load function â€" runs on GET, returns data for the template */
     load?: (ctx: RouteContext) => Promise<Record<string, any>> | Record<string, any>;
-    /** Form actions — keyed by action name */
+    /** Form actions â€" keyed by action name */
     actions?: Record<string, (formData: FormData, env: Env, ctx: RouteContext) => Promise<any>>;
-    /** RPC functions — callable from client via fetch */
+    /** RPC functions â€" callable from client via fetch */
     rpc?: Record<string, (args: any[], env: Env, ctx: RouteContext) => Promise<any>>;
-    /** Render function — returns HTML string from data */
+    /** Render function â€" returns HTML string from data */
     render: (data: Record<string, any>) => string;
     /** Layout name (default: 'default') */
     layout?: string;
 }
+/** HTTP methods supported by API routes */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/** A compiled API route module (route.ts) — returns raw Response objects */
+export interface ApiRouteModule {
+    /** Pattern string (e.g., '/api/v1/health', '/api/v1/db/:name') */
+    pattern: string;
+    /** Marker that distinguishes API routes from page routes */
+    __api: true;
+    /** Method handlers — keyed by HTTP method */
+    [method: string]: ((ctx: RouteContext) => Promise<Response> | Response) | string | boolean;
+}
 /** Layout module */
 export interface LayoutModule {
-    /** Render function — wraps page content */
+    /** Render function â€" wraps page content */
     render: (data: {
         content: string;
         data: Record<string, any>;
         head?: string;
     }) => string;
 }
-/** App configuration (internal — used by compiler-generated code) */
+/** App configuration (internal â€" used by compiler-generated code) */
 export interface AppConfig<E extends Env = Env> {
-    /** Route modules — generated by compiler or defined manually */
-    routes?: RouteModule[];
-    /** Layout modules — keyed by name */
+    /** Route modules â€" generated by compiler or defined manually */
+    routes?: (RouteModule | ApiRouteModule)[];
+    /** Layout modules â€" keyed by name */
     layouts?: Record<string, LayoutModule>;
     /** Static file directory (relative to project root) */
     publicDir?: string;
 }
-/** Database schema config — maps a binding name to its schema */
+/** Database schema config â€" maps a binding name to its schema */
 export interface DatabaseConfig {
     /** Schema definition (SchemaDsl or DatabaseSchema from @kuratchi/orm) */
     schema: any;
@@ -61,7 +72,7 @@ export interface DatabaseConfig {
     skipMigrations?: boolean;
 }
 /**
- * Framework configuration — the user-facing config file (kuratchi.config.ts)
+ * Framework configuration â€" the user-facing config file (kuratchi.config.ts)
  *
  * @example
  * ```ts
@@ -79,20 +90,21 @@ export interface DatabaseConfig {
  * ```
  */
 export interface kuratchiConfig<E extends Env = Env> {
-    /** ORM configuration — schema definitions and auto-migration */
+    /** ORM configuration â€" schema definitions and auto-migration */
     orm?: {
         /** Map of D1 binding names to their database configs */
-        databases: Record<string, DatabaseConfig>;
+        databases?: Record<string, DatabaseConfig>;
+        [key: string]: any;
     };
-    /** UI configuration — opt into @kuratchi/ui theme and components */
+    /** UI configuration â€" opt into @kuratchi/ui theme and components */
     ui?: {
         /** Theme to inject: 'default' uses @kuratchi/ui's built-in theme, or a path to a custom CSS file */
         theme?: 'default' | string;
     };
-    /** Auth configuration — @kuratchi/auth plugin setup */
-    auth?: AuthConfig;
+    /** Auth configuration â€" @kuratchi/auth plugin setup */
+    auth?: AuthConfig | Record<string, any>;
     /**
-     * Durable Object configuration — config-driven DO class generation.
+     * Durable Object configuration â€" config-driven DO class generation.
      *
      * Map a DO namespace binding to its class name and optional configuration.
      * Supports string shorthand or an object with stubId option.
@@ -100,12 +112,12 @@ export interface kuratchiConfig<E extends Env = Env> {
      * @example
      * ```ts
      * durableObjects: {
-     *   // Object form — stubId tells the framework which user field identifies the stub
+     *   // Object form â€" stubId tells the framework which user field identifies the stub
      *   ORG_DB: {
      *     className: 'OrganizationDO',
      *     stubId: 'user.orgId'
      *   },
-     *   // String shorthand — className only, no auto-stub resolution
+     *   // String shorthand â€" className only, no auto-stub resolution
      *   CACHE_DB: 'CacheDO'
      * }
      * ```
@@ -114,6 +126,22 @@ export interface kuratchiConfig<E extends Env = Env> {
         className: string;
         /** The user field path that identifies the DO stub (e.g. 'user.orgId') */
         stubId?: string;
+        /** DO source files (e.g. ['auth.do.ts', 'sites.do.ts']) */
+        files?: string[];
+    }>;
+    /** Container classes exported into the generated worker entry. */
+    containers?: Record<string, string | {
+        /** Relative path from project root. Must end in `.container.ts|js|mjs|cjs`. */
+        file: string;
+        /** Optional override; inferred from exported class in `file` when omitted. */
+        className?: string;
+    }>;
+    /** Workflow classes exported into the generated worker entry. */
+    workflows?: Record<string, string | {
+        /** Relative path from project root. Must end in `.workflow.ts|js|mjs|cjs`. */
+        file: string;
+        /** Optional override; inferred from exported class in `file` when omitted. */
+        className?: string;
     }>;
 }
 /** Auth configuration for kuratchi.config.ts */
@@ -124,7 +152,7 @@ export interface AuthConfig {
     secretEnvKey?: string;
     /** Enable session parsing on every request (default: true) */
     sessionEnabled?: boolean;
-    /** Credentials config — enables signUp/signIn/signOut/getCurrentUser */
+    /** Credentials config â€" enables signUp/signIn/signOut/getCurrentUser */
     credentials?: {
         /** D1 binding name for auth database (default: 'DB') */
         binding?: string;
@@ -140,16 +168,17 @@ export interface AuthConfig {
         signInRedirect?: string;
         /** Redirect after signout (default: '/auth/login') */
         signOutRedirect?: string;
+        [key: string]: any;
     };
-    /** Activity tracking config — enables logActivity/getActivity */
+    /** Activity tracking config â€" enables logActivity/getActivity */
     activity?: Record<string, {
         label: string;
         severity?: 'info' | 'warning' | 'critical';
         category?: string;
     }>;
-    /** Role definitions — enables hasRole/hasPermission/assignRole */
+    /** Role definitions â€" enables hasRole/hasPermission/assignRole */
     roles?: Record<string, string[]>;
-    /** OAuth providers config — enables startOAuth/handleOAuthCallback */
+    /** OAuth providers config â€" enables startOAuth/handleOAuthCallback */
     oauth?: {
         providers?: Record<string, {
             clientIdEnv: string;
@@ -158,14 +187,16 @@ export interface AuthConfig {
         }>;
         /** Redirect after OAuth login (default: '/admin') */
         loginRedirect?: string;
+        [key: string]: any;
     };
-    /** Route guards — protect paths, redirect if not authenticated */
+    /** Route guards â€" protect paths, redirect if not authenticated */
     guards?: {
         paths?: string[];
         exclude?: string[];
         redirectTo?: string;
+        [key: string]: any;
     };
-    /** Rate limiting — throttle requests per route */
+    /** Rate limiting â€" throttle requests per route */
     rateLimit?: {
         defaultWindowMs?: number;
         defaultMaxRequests?: number;
@@ -179,12 +210,13 @@ export interface AuthConfig {
             windowMs?: number;
             message?: string;
         }[];
+        [key: string]: any;
     };
-    /** Turnstile bot protection — verify Cloudflare Turnstile tokens */
+    /** Turnstile bot protection â€" verify Cloudflare Turnstile tokens */
     turnstile?: {
         /** Env var name for Turnstile secret key (default: 'TURNSTILE_SECRET') */
         secretEnv?: string;
-        /** Env var name for Turnstile site key (default: 'TURNSTILE_SITE_KEY') — exposed to client */
+        /** Env var name for Turnstile site key (default: 'TURNSTILE_SITE_KEY') â€" exposed to client */
         siteKeyEnv?: string;
         /** Skip Turnstile verification in dev mode (default: true) */
         skipInDev?: boolean;
@@ -198,10 +230,30 @@ export interface AuthConfig {
             message?: string;
             expectedAction?: string;
         }[];
+        [key: string]: any;
     };
-    /** Organization multi-tenancy — DO-backed per-org databases */
+    /** Organization multi-tenancy â€" DO-backed per-org databases */
     organizations?: {
         /** DO namespace binding name in env (e.g. 'ORG_DB') */
-        binding: string;
-    };
+        binding?: string;
+        [key: string]: any;
+    } | Record<string, any>;
+}
+/** Runtime pipeline context - shared across runtime step handlers */
+export interface RuntimeContext<E extends Env = Env> {
+    request: Request;
+    env: E;
+    ctx: ExecutionContext;
+    url: URL;
+    params: Record<string, string>;
+    locals: Record<string, any>;
+}
+export type RuntimeNext = () => Promise<Response>;
+export type RuntimeErrorResult = Response | null | undefined | void;
+export interface RuntimeStep<E extends Env = Env> {
+    request?: (ctx: RuntimeContext<E>, next: RuntimeNext) => Promise<Response> | Response;
+    route?: (ctx: RuntimeContext<E>, next: RuntimeNext) => Promise<Response> | Response;
+    response?: (ctx: RuntimeContext<E>, response: Response) => Promise<Response> | Response;
+    error?: (ctx: RuntimeContext<E>, error: unknown) => Promise<RuntimeErrorResult> | RuntimeErrorResult;
 }
+export type RuntimeDefinition<E extends Env = Env> = Record<string, RuntimeStep<E>>;

package/package.json

@@ -1,46 +1,48 @@
 {
-    "name":  "@kuratchi/js",
-    "version":  "0.0.2",
-    "description":  "A thin, Cloudflare Workers-native web framework with Svelte-inspired syntax",
-    "type":  "module",
-    "main":  "./dist/index.js",
-    "types":  "./dist/index.d.ts",
-    "bin":  {
-                "kuratchi":  "./dist/cli.js"
-            },
-    "files":  [
-                  "dist",
-                  "README.md"
-              ],
-    "scripts":  {
-                    "build":  "tsc -p tsconfig.build.json",
-                    "check":  "tsc -p tsconfig.build.json --noEmit",
-                    "prepublishOnly":  "npm run build"
-                },
-    "exports":  {
-                    ".":  {
-                              "types":  "./dist/index.d.ts",
-                              "import":  "./dist/index.js"
-                          },
-                    "./runtime/context.js":  {
-                                                 "types":  "./dist/runtime/context.d.ts",
-                                                 "import":  "./dist/runtime/context.js"
-                                             },
-                    "./runtime/do.js":  {
-                                            "types":  "./dist/runtime/do.d.ts",
-                                            "import":  "./dist/runtime/do.js"
-                                        },
-                    "./package.json":  "./package.json"
-                },
-    "engines":  {
-                    "node":  "\u003e=18"
-                },
-    "publishConfig":  {
-                          "access":  "public"
-                      },
-    "devDependencies":  {
-                            "@cloudflare/workers-types":  "^4.20260223.0",
-                            "@types/node":  "^24.4.0",
-                            "typescript":  "^5.8.0"
-                        }
-}
+    "name": "@kuratchi/js",
+    "version": "0.0.4",
+    "description": "A thin, Cloudflare Workers-native web framework with Svelte-inspired syntax",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "bin": {
+        "kuratchi": "./dist/cli.js"
+    },
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json",
+        "check": "tsc -p tsconfig.build.json --noEmit",
+        "test": "bun test",
+        "test:watch": "bun test --watch",
+        "prepublishOnly": "npm run build"
+    },
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./runtime/context.js": {
+            "types": "./dist/runtime/context.d.ts",
+            "import": "./dist/runtime/context.js"
+        },
+        "./runtime/do.js": {
+            "types": "./dist/runtime/do.d.ts",
+            "import": "./dist/runtime/do.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "engines": {
+        "node": "\u003e=18"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "devDependencies": {
+        "@cloudflare/workers-types": "^4.20260223.0",
+        "@types/node": "^24.4.0",
+        "typescript": "^5.8.0"
+    }
+}