@kuratchi/js 0.0.20 → 0.0.21

package/README.md

@@ -831,12 +831,21 @@ import {
 } from '@kuratchi/js';
 ```
 
+### Virtual Modules
+
+Kuratchi provides virtual modules for request-scoped state. Use these in route files:
+
+| Virtual Module | Description |
+|----------------|-------------|
+| `kuratchi:request` | Request state: `url`, `params`, `searchParams`, `headers`, `locals`, etc. |
+| `kuratchi:navigation` | Server-side redirect helper |
+
 ### Request helpers
 
-For a batteries-included request layer, import pre-parsed request state from `@kuratchi/js/request`:
+For a batteries-included request layer, import pre-parsed request state from `kuratchi:request`:
 
 ```ts
-import { url, pathname, searchParams, params, slug } from '@kuratchi/js/request';
+import { url, pathname, searchParams, params, slug, locals } from 'kuratchi:request';
 
 const page = pathname;
 const tab = searchParams.get('tab');
@@ -849,9 +858,23 @@ const postSlug = slug;
 - `searchParams` is `url.searchParams` for the current request.
 - `params` is the matched route params object, like `{ slug: 'hello-world' }`.
 - `slug` is `params.slug` when the matched route defines a `slug` param.
-- `headers` and `method` are also exported from `@kuratchi/js/request`.
-- `params` is not ambient; import it from `@kuratchi/js/request` or use `getParams()` / `getParam()` from `@kuratchi/js`.
-- Use `getRequest()` when you want the raw native `Request` object.
+- `headers` and `method` are also exported from `kuratchi:request`.
+- `locals` is the request-scoped locals object (typed via `App.Locals` in `app.d.ts`).
+- Use `getRequest()` from `@kuratchi/js` when you want the raw native `Request` object.
+
+### Server-side redirect
+
+Import `redirect` from `kuratchi:navigation` for server-side redirects:
+
+```ts
+import { redirect } from 'kuratchi:navigation';
+
+// Redirect to another page (throws RedirectError, caught by framework)
+redirect('/dashboard');
+redirect('/login', 302);
+```
+
+`redirect()` works in route scripts, `$server/` modules, and form actions. It throws a `RedirectError` that the framework catches and converts to a proper HTTP redirect response (default 303 for POST-Redirect-GET).
 
 ## Runtime Hook
 

package/dist/cli.js

@@ -29,6 +29,9 @@ async function main() {
         case 'create':
             await runCreate();
             return;
+        case 'types':
+            await runTypes();
+            return;
         default:
             console.log(`
 KuratchiJS CLI
@@ -38,6 +41,7 @@ Usage:
   kuratchi build          Compile routes once
   kuratchi dev            Compile, watch for changes, and start wrangler dev server
   kuratchi watch          Compile + watch only (no wrangler — for custom setups)
+  kuratchi types          Generate TypeScript types from schema to src/app.d.ts
 `);
             process.exit(1);
     }
@@ -49,6 +53,10 @@ async function runCreate() {
     const positional = remaining.filter(a => !a.startsWith('-'));
     await create(positional[0], flags);
 }
+async function runTypes() {
+    const { writeAppTypes } = await import('./compiler/type-generator.js');
+    writeAppTypes({ projectDir });
+}
 async function runBuild(isDev = false) {
     console.log('[kuratchi] Compiling...');
     try {

package/dist/compiler/component-pipeline.js

@@ -97,7 +97,15 @@ export function createComponentCompiler(options) {
         const scopeOpen = `__parts.push('<div class="${scopeHash}">');`;
         const scopeClose = `__parts.push('</div>');`;
         const bodyLines = body.split('\n');
-        const scopedBody = [bodyLines[0], scopeOpen, ...bodyLines.slice(1), scopeClose].join('\n');
+        const insertIndex = bodyLines.findIndex(l => l.startsWith('let __html'));
+        const safeInsertIndex = insertIndex === -1 ? bodyLines.length : insertIndex;
+        const scopedBody = [
+            bodyLines[0],
+            scopeOpen,
+            ...bodyLines.slice(1, safeInsertIndex),
+            scopeClose,
+            ...bodyLines.slice(safeInsertIndex)
+        ].join('\n');
         const fnBody = effectivePropsCode ? `${effectivePropsCode}\n  ${scopedBody}` : scopedBody;
         const compiled = `function ${funcName}(props, __esc) {\n  ${fnBody}\n  return __html;\n}`;
         compiledComponentCache.set(fileName, compiled);

package/dist/compiler/server-module-pipeline.js

@@ -37,6 +37,12 @@ export function createServerModuleCompiler(options) {
         return resolveExistingModuleFile(proxyNoExt) ?? (fs.existsSync(proxyNoExt + '.ts') ? proxyNoExt + '.ts' : null);
     }
     function resolveImportTarget(importerAbs, spec) {
+        // Handle kuratchi:* virtual modules
+        if (spec.startsWith('kuratchi:')) {
+            // These are resolved at bundle time to @kuratchi/js runtime modules
+            // Return null to keep the specifier as-is for later rewriting
+            return null;
+        }
         if (spec.startsWith('$')) {
             const slashIdx = spec.indexOf('/');
             const folder = slashIdx === -1 ? spec.slice(1) : spec.slice(1, slashIdx);
@@ -70,6 +76,15 @@ export function createServerModuleCompiler(options) {
         }
         const source = fs.readFileSync(resolved, 'utf-8');
         const rewriteSpecifier = (spec) => {
+            // Rewrite kuratchi:* virtual modules to @kuratchi/js runtime paths
+            if (spec.startsWith('kuratchi:')) {
+                const moduleName = spec.slice('kuratchi:'.length);
+                const moduleMap = {
+                    'request': '@kuratchi/js/request',
+                    'navigation': '@kuratchi/js/navigation',
+                };
+                return moduleMap[moduleName] ?? spec;
+            }
             const target = resolveImportTarget(resolved, spec);
             if (!target)
                 return spec;
@@ -96,6 +111,15 @@ export function createServerModuleCompiler(options) {
         return outPath;
     }
     function resolveCompiledImportPath(origPath, importerDir, outFileDir) {
+        // Rewrite kuratchi:* virtual modules to @kuratchi/js runtime paths
+        if (origPath.startsWith('kuratchi:')) {
+            const moduleName = origPath.slice('kuratchi:'.length);
+            const moduleMap = {
+                'request': '@kuratchi/js/request',
+                'navigation': '@kuratchi/js/navigation',
+            };
+            return moduleMap[moduleName] ?? origPath;
+        }
         const isBareModule = !origPath.startsWith('.') && !origPath.startsWith('/') && !origPath.startsWith('$');
         if (isBareModule)
             return origPath;

package/dist/compiler/type-generator.d.ts

@@ -0,0 +1,8 @@
+export interface GenerateTypesOptions {
+    projectDir: string;
+    schemaPath?: string;
+    outputPath?: string;
+    localsInterface?: string;
+}
+export declare function generateAppTypes(options: GenerateTypesOptions): string;
+export declare function writeAppTypes(options: GenerateTypesOptions): void;

package/dist/compiler/type-generator.js

@@ -0,0 +1,124 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+function sqliteTypeToTs(sqlType) {
+    const lower = sqlType.toLowerCase();
+    if (lower.includes('integer') || lower.includes('int') || lower.includes('real') || lower.includes('numeric')) {
+        return 'number';
+    }
+    if (lower.includes('text') || lower.includes('varchar') || lower.includes('char')) {
+        return 'string';
+    }
+    if (lower.includes('blob')) {
+        return 'Uint8Array';
+    }
+    if (lower.includes('json')) {
+        return 'Record<string, unknown>';
+    }
+    if (lower.includes('boolean') || lower.includes('bool')) {
+        return 'boolean';
+    }
+    return 'unknown';
+}
+function parseSchemaColumn(name, definition) {
+    const lower = definition.toLowerCase();
+    const nullable = !lower.includes('not null');
+    const hasDefault = lower.includes('default');
+    const type = sqliteTypeToTs(definition);
+    return { name, type, nullable, hasDefault };
+}
+function parseSchemaFromSource(source) {
+    const tables = [];
+    // Match tables: { tableName: { col: 'def', ... }, ... }
+    const tablesMatch = source.match(/tables\s*:\s*\{([\s\S]*?)\n\t?\}/);
+    if (!tablesMatch)
+        return tables;
+    const tablesBlock = tablesMatch[1];
+    // Match each table definition
+    const tableRegex = /(\w+)\s*:\s*\{([^}]+)\}/g;
+    let match;
+    while ((match = tableRegex.exec(tablesBlock)) !== null) {
+        const tableName = match[1];
+        const columnsBlock = match[2];
+        const columns = [];
+        // Match each column: name: 'definition'
+        const colRegex = /(\w+)\s*:\s*['"]([^'"]+)['"]/g;
+        let colMatch;
+        while ((colMatch = colRegex.exec(columnsBlock)) !== null) {
+            columns.push(parseSchemaColumn(colMatch[1], colMatch[2]));
+        }
+        tables.push({ name: tableName, columns });
+    }
+    return tables;
+}
+function generateTableTypes(tables) {
+    const lines = [];
+    for (const table of tables) {
+        const pascalName = table.name
+            .split('_')
+            .map(s => s.charAt(0).toUpperCase() + s.slice(1))
+            .join('');
+        lines.push(`    /** Row type for ${table.name} table */`);
+        lines.push(`    interface ${pascalName}Row {`);
+        for (const col of table.columns) {
+            const optional = col.nullable || col.hasDefault ? '?' : '';
+            lines.push(`      ${col.name}${optional}: ${col.type};`);
+        }
+        lines.push(`    }`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+export function generateAppTypes(options) {
+    const { projectDir, schemaPath = 'src/server/schema.ts', outputPath = 'src/app.d.ts', localsInterface, } = options;
+    const schemaFullPath = path.join(projectDir, schemaPath);
+    let tables = [];
+    if (fs.existsSync(schemaFullPath)) {
+        const schemaSource = fs.readFileSync(schemaFullPath, 'utf-8');
+        tables = parseSchemaFromSource(schemaSource);
+    }
+    const tableTypes = tables.length > 0 ? generateTableTypes(tables) : '';
+    // Check if user has existing Locals definition to preserve
+    const outputFullPath = path.join(projectDir, outputPath);
+    let existingLocals = null;
+    if (fs.existsSync(outputFullPath)) {
+        const existing = fs.readFileSync(outputFullPath, 'utf-8');
+        // Extract user-defined Locals interface (between USER LOCALS START/END markers)
+        const localsMatch = existing.match(/\/\/ USER LOCALS START\n([\s\S]*?)\/\/ USER LOCALS END/);
+        if (localsMatch) {
+            existingLocals = localsMatch[1];
+        }
+    }
+    const localsBlock = existingLocals || localsInterface || `    interface Locals {
+      userId: number;
+      userEmail: string;
+    }`;
+    const output = `/**
+ * Type declarations for kuratchi app.
+ * 
+ * DB types are auto-generated from schema.ts - regenerate with: kuratchi types
+ * Edit the Locals interface below to match your runtime.hook.ts
+ */
+declare global {
+  namespace App {
+    /** Request-scoped locals set by runtime hooks */
+// USER LOCALS START
+${localsBlock}
+// USER LOCALS END
+
+${tableTypes ? `    // Database table row types (auto-generated from schema.ts)\n${tableTypes}` : ''}  }
+}
+
+export {};
+`;
+    return output;
+}
+export function writeAppTypes(options) {
+    const output = generateAppTypes(options);
+    const outputPath = path.join(options.projectDir, options.outputPath || 'src/app.d.ts');
+    const dir = path.dirname(outputPath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(outputPath, output, 'utf-8');
+    console.log(`[kuratchi] Generated types → ${path.relative(options.projectDir, outputPath)}`);
+}

package/dist/runtime/context.d.ts

@@ -43,7 +43,9 @@ export declare function getParam(name: string): string | undefined;
  * Throws a redirect signal consumed by the framework's PRG flow.
  */
 export declare function redirect(path: string, status?: number): never;
-/** Backward-compatible alias for redirect() */
+/**
+ * @deprecated Use redirect() instead. This alias will be removed in a future version.
+ */
 export declare function goto(path: string, status?: number): never;
 export declare function setBreadcrumbs(items: BreadcrumbItem[]): void;
 export declare function getBreadcrumbs(): BreadcrumbItem[];

package/dist/runtime/context.js

@@ -104,7 +104,9 @@ export function redirect(path, status = 303) {
     __locals.__redirectStatus = status;
     throw new RedirectError(path, status);
 }
-/** Backward-compatible alias for redirect() */
+/**
+ * @deprecated Use redirect() instead. This alias will be removed in a future version.
+ */
 export function goto(path, status = 303) {
     redirect(path, status);
 }

package/dist/runtime/navigation.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Navigation helpers for kuratchi routes.
+ * Import via: import { redirect } from 'kuratchi:navigation';
+ *
+ * redirect() is server-side only — works in route scripts, server modules, and form actions.
+ * It throws a RedirectError that the framework catches and converts to a 303 redirect response.
+ */
+export { redirect } from './context.js';

package/dist/runtime/navigation.js

@@ -0,0 +1,8 @@
+/**
+ * Navigation helpers for kuratchi routes.
+ * Import via: import { redirect } from 'kuratchi:navigation';
+ *
+ * redirect() is server-side only — works in route scripts, server modules, and form actions.
+ * It throws a RedirectError that the framework catches and converts to a 303 redirect response.
+ */
+export { redirect } from './context.js';

package/dist/runtime/request.d.ts

@@ -1,3 +1,11 @@
+declare global {
+    namespace App {
+        /** Request-scoped locals set by runtime hooks. Extend in your app.d.ts */
+        interface Locals {
+            [key: string]: unknown;
+        }
+    }
+}
 export declare let url: URL;
 export declare let pathname: string;
 export declare let searchParams: URLSearchParams;
@@ -5,5 +13,25 @@ export declare let headers: Headers;
 export declare let method: string;
 export declare let params: Record<string, string>;
 export declare let slug: string | undefined;
+/**
+ * Get request-scoped locals with full type safety.
+ * Define your Locals type in src/app.d.ts:
+ * ```
+ * declare global {
+ *   namespace App {
+ *     interface Locals {
+ *       userId: number;
+ *       userEmail: string;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare function getLocals(): App.Locals;
+/**
+ * Direct access to request-scoped locals.
+ * Type is inferred from App.Locals declared in your app.d.ts.
+ */
+export declare const locals: App.Locals;
 export declare function __setRequestState(request: Request): void;
 export declare function __setRequestParams(nextParams: Record<string, string> | null | undefined): void;

package/dist/runtime/request.js

@@ -1,3 +1,4 @@
+import { __getLocals } from './context.js';
 export let url = new URL('http://localhost/');
 export let pathname = '/';
 export let searchParams = url.searchParams;
@@ -5,6 +6,49 @@ export let headers = new Headers();
 export let method = 'GET';
 export let params = {};
 export let slug = undefined;
+/**
+ * Get request-scoped locals with full type safety.
+ * Define your Locals type in src/app.d.ts:
+ * ```
+ * declare global {
+ *   namespace App {
+ *     interface Locals {
+ *       userId: number;
+ *       userEmail: string;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export function getLocals() {
+    return __getLocals();
+}
+/**
+ * Direct access to request-scoped locals.
+ * Type is inferred from App.Locals declared in your app.d.ts.
+ */
+export const locals = new Proxy({}, {
+    get(_target, prop) {
+        return __getLocals()[prop];
+    },
+    set(_target, prop, value) {
+        __getLocals()[prop] = value;
+        return true;
+    },
+    has(_target, prop) {
+        return prop in __getLocals();
+    },
+    ownKeys() {
+        return Reflect.ownKeys(__getLocals());
+    },
+    getOwnPropertyDescriptor(_target, prop) {
+        const locals = __getLocals();
+        if (prop in locals) {
+            return { configurable: true, enumerable: true, value: locals[prop] };
+        }
+        return undefined;
+    },
+});
 function __syncDerivedState() {
     pathname = url.pathname;
     searchParams = url.searchParams;

package/package.json

@@ -1,72 +1,76 @@
-{
-    "name": "@kuratchi/js",
-    "version": "0.0.20",
-    "description": "A thin, Cloudflare Workers-native web framework with Svelte-inspired syntax",
-    "license": "MIT",
-    "type": "module",
-    "main": "./dist/index.js",
-    "types": "./dist/index.d.ts",
-    "bin": {
-        "kuratchi": "dist/cli.js"
-    },
-    "files": [
-        "dist",
-        "README.md",
-        "LICENSE"
-    ],
-    "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"
-        },
-        "./request": {
-            "types": "./dist/runtime/request.d.ts",
-            "import": "./dist/runtime/request.js"
-        },
-        "./runtime/do.js": {
-            "types": "./dist/runtime/do.d.ts",
-            "import": "./dist/runtime/do.js"
-        },
-        "./runtime/schema.js": {
-            "types": "./dist/runtime/schema.d.ts",
-            "import": "./dist/runtime/schema.js"
-        },
-        "./runtime/generated-worker.js": {
-            "types": "./dist/runtime/generated-worker.d.ts",
-            "import": "./dist/runtime/generated-worker.js"
-        },
-        "./compiler": {
-            "types": "./dist/compiler/index.d.ts",
-            "import": "./dist/compiler/index.js"
-        },
-        "./environment": {
-            "types": "./dist/index.d.ts",
-            "import": "./dist/index.js"
-        },
-        "./package.json": "./package.json"
-    },
-    "engines": {
-        "node": ">=18"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "dependencies": {
-        "typescript": "^5.8.0"
-    },
-    "devDependencies": {
-        "@cloudflare/workers-types": "^4.20260223.0",
-        "@types/node": "^24.4.0"
-    }
-}
+{
+    "name": "@kuratchi/js",
+    "version": "0.0.21",
+    "description": "A thin, Cloudflare Workers-native web framework with Svelte-inspired syntax",
+    "license": "MIT",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "bin": {
+        "kuratchi": "dist/cli.js"
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE"
+    ],
+    "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"
+        },
+        "./request": {
+            "types": "./dist/runtime/request.d.ts",
+            "import": "./dist/runtime/request.js"
+        },
+        "./navigation": {
+            "types": "./dist/runtime/navigation.d.ts",
+            "import": "./dist/runtime/navigation.js"
+        },
+        "./runtime/do.js": {
+            "types": "./dist/runtime/do.d.ts",
+            "import": "./dist/runtime/do.js"
+        },
+        "./runtime/schema.js": {
+            "types": "./dist/runtime/schema.d.ts",
+            "import": "./dist/runtime/schema.js"
+        },
+        "./runtime/generated-worker.js": {
+            "types": "./dist/runtime/generated-worker.d.ts",
+            "import": "./dist/runtime/generated-worker.js"
+        },
+        "./compiler": {
+            "types": "./dist/compiler/index.d.ts",
+            "import": "./dist/compiler/index.js"
+        },
+        "./environment": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "engines": {
+        "node": ">=18"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "dependencies": {
+        "typescript": "^5.8.0"
+    },
+    "devDependencies": {
+        "@cloudflare/workers-types": "^4.20260223.0",
+        "@types/node": "^24.4.0"
+    }
+}