toiljs 0.0.37 → 0.0.38

package/src/cli/create.ts

@@ -270,96 +270,31 @@ function scaffold(
  * editor their shapes. Auto-included via the server tsconfig and ignored by the
  * compiler. Keep in sync with `toiljs/server/runtime/http/*`.
  */
-const TOIL_SERVER_ENV_DTS = `/**
- * Editor-only ambient declarations for the toiljs cookie globals.
- *
- * \`Cookie\`, \`Cookies\`, \`SecureCookies\`, and the \`SameSite\` / \`CookieEncoding\` /
- * \`CookiePrefix\` enums are \`@global\` in the toiljs server runtime, so a handler
- * uses them with no import (exactly like \`crypto\`). The toilscript compiler
- * registers them from the runtime; this file just gives the editor their shapes.
- * It is auto-included by the server tsconfig and ignored by the compiler.
- */
-
-declare enum SameSite {
-    Default = 0,
-    None = 1,
-    Lax = 2,
-    Strict = 3,
-}
-
-declare enum CookieEncoding {
-    Percent = 0,
-    Raw = 1,
-    Base64Url = 2,
-}
-
-declare enum CookiePrefix {
-    None = 0,
-    Secure = 1,
-    Host = 2,
-}
-
-declare class CookieValidation {
-    valid: bool;
-    errors: Array<string>;
-    fail(msg: string): void;
-}
-
-declare class Cookie {
-    name: string;
-    value: string;
-    encoding: CookieEncoding;
-    constructor(name: string, value: string);
-    static create(name: string, value: string): Cookie;
-    domain(v: string): Cookie;
-    path(v: string): Cookie;
-    maxAge(seconds: i64): Cookie;
-    expires(epochSeconds: i64): Cookie;
-    expiresRaw(date: string): Cookie;
-    secure(on?: bool): Cookie;
-    httpOnly(on?: bool): Cookie;
-    sameSite(s: SameSite): Cookie;
-    partitioned(on?: bool): Cookie;
-    priority(p: string): Cookie;
-    extension(av: string): Cookie;
-    withEncoding(e: CookieEncoding): Cookie;
-    asSecurePrefixed(): Cookie;
-    asHostPrefixed(): Cookie;
-    detectedPrefix(): CookiePrefix;
-    encodedValue(): string;
-    validate(): CookieValidation;
-    serialize(strict?: bool): string;
-    toString(): string;
-}
-
-declare class CookieMap {
-    set(name: string, value: string): void;
-    get(name: string): string | null;
-    has(name: string): bool;
-    names(): Array<string>;
-    readonly size: i32;
-}
-
-declare class Cookies {
-    static parse(cookieHeader: string): CookieMap;
-    static get(cookieHeader: string, name: string): string | null;
-    static serialize(name: string, value: string): string;
-    static parseSetCookie(setCookie: string): Cookie;
-    static encodeValue(raw: string): string;
-    static decodeValue(enc: string): string;
-}
-
-declare class SecureCookies {
-    static signed(key: Uint8Array): SecureCookies;
-    static encrypted(key: Uint8Array): SecureCookies;
-    addKey(key: Uint8Array): SecureCookies;
-    sign(name: string, value: string): string;
-    unsign(name: string, sealed: string): string | null;
-    encrypt(name: string, value: string): string;
-    decrypt(name: string, sealed: string): string | null;
-    seal(cookie: Cookie): Cookie;
-    open(jar: CookieMap, name: string): string | null;
-}
+// Editor-only ambient declarations for the server-runtime globals, scaffolded
+// into the server dir. Kept BYTE-IDENTICAL to `TOIL_SERVER_ENV_DTS` in
+// src/compiler/generate.ts (which `toiljs build`/`dev` regenerate, and `doctor
+// --fix` rewrites), so create / build / doctor never disagree and flip-flop.
+export const TOIL_SERVER_ENV_DTS = `// AUTO-GENERATED by toil, do not edit. Editor-only ambient declarations for
+// the toiljs server-runtime globals (Cookie, Cookies, SecureCookies, the
+// cookie enums): @global in the runtime, used with no import. These alias the
+// real runtime types so a global-built Cookie is exactly what Response.setCookie
+// / SecureCookies.seal expect. The toilscript compiler registers them itself.
+declare const SameSite: typeof import('toiljs/server/runtime/http/cookie').SameSite;
+type SameSite = import('toiljs/server/runtime/http/cookie').SameSite;
+declare const CookieEncoding: typeof import('toiljs/server/runtime/http/cookie').CookieEncoding;
+type CookieEncoding = import('toiljs/server/runtime/http/cookie').CookieEncoding;
+declare const CookiePrefix: typeof import('toiljs/server/runtime/http/cookie').CookiePrefix;
+type CookiePrefix = import('toiljs/server/runtime/http/cookie').CookiePrefix;
+declare const CookieValidation: typeof import('toiljs/server/runtime/http/cookie').CookieValidation;
+type CookieValidation = import('toiljs/server/runtime/http/cookie').CookieValidation;
+declare const Cookie: typeof import('toiljs/server/runtime/http/cookie').Cookie;
+type Cookie = import('toiljs/server/runtime/http/cookie').Cookie;
+declare const CookieMap: typeof import('toiljs/server/runtime/http/cookies').CookieMap;
+type CookieMap = import('toiljs/server/runtime/http/cookies').CookieMap;
+declare const Cookies: typeof import('toiljs/server/runtime/http/cookies').Cookies;
+type Cookies = import('toiljs/server/runtime/http/cookies').Cookies;
+declare const SecureCookies: typeof import('toiljs/server/runtime/http/securecookies').SecureCookies;
+type SecureCookies = import('toiljs/server/runtime/http/securecookies').SecureCookies;
 `;
 
 /**

package/src/cli/doctor.ts

@@ -10,7 +10,7 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { loadConfig, type ResolvedToilConfig, scanRoutes } from 'toiljs/compiler';
+import { loadConfig, type ResolvedToilConfig, scanRoutes, TOIL_SERVER_ENV_DTS } from 'toiljs/compiler';
 
 import {
     type Check,
@@ -330,6 +330,32 @@ function applyRpcFix(root: string): RpcFixResult {
         changed.push('.gitignore');
     }
 
+    // Migrate the editor-only server-globals d.ts to the current shapes (the
+    // exact content `toiljs build`/`dev` regenerate), in each server source dir.
+    // This is what fixes a stale, scaffolded `toil-server-env.d.ts` whose
+    // standalone class decls made a second, incompatible `Cookie`.
+    const serverToilconfig = readJsonObject(path.join(root, 'toilconfig.json'));
+    if (serverToilconfig !== null) {
+        const entries = Array.isArray(serverToilconfig.entries)
+            ? (serverToilconfig.entries as unknown[]).filter((e): e is string => typeof e === 'string')
+            : [];
+        const dirs = new Set<string>();
+        for (const e of entries) dirs.add(path.dirname(path.resolve(root, e)));
+        if (dirs.size === 0) dirs.add(path.join(root, 'server'));
+        for (const dir of dirs) {
+            const envPath = path.join(dir, 'toil-server-env.d.ts');
+            if (readFile(envPath) !== TOIL_SERVER_ENV_DTS) {
+                try {
+                    fs.mkdirSync(dir, { recursive: true });
+                    writeFile(envPath, TOIL_SERVER_ENV_DTS);
+                    changed.push(path.relative(root, envPath));
+                } catch {
+                    // editor-only; ignore write failures
+                }
+            }
+        }
+    }
+
     return { changed, skipped };
 }
 

package/src/compiler/generate.ts

@@ -76,6 +76,39 @@ export const TOIL_ENV_DTS =
     `    export const pages: import('toiljs/client').PageMeta[];\n` +
     `}\n`;
 
+/**
+ * Contents of `<serverDir>/toil-server-env.d.ts`: editor-only ambient
+ * declarations for the toiljs server-runtime globals. ALIASES the real runtime
+ * types (the same trick the IO globals use above), so a global-built `Cookie`
+ * is the exact type the runtime APIs (`Response.setCookie`, `SecureCookies.seal`)
+ * expect; redeclaring them as standalone classes makes a second, nominally-
+ * incompatible `Cookie` (private fields). Regenerated by `buildServer` on every
+ * build/dev so existing projects auto-migrate. Keep the declarations in sync
+ * with the `toiljs create` scaffold (`src/cli/create.ts`).
+ */
+export const TOIL_SERVER_ENV_DTS =
+    `// AUTO-GENERATED by toil, do not edit. Editor-only ambient declarations for\n` +
+    `// the toiljs server-runtime globals (Cookie, Cookies, SecureCookies, the\n` +
+    `// cookie enums): @global in the runtime, used with no import. These alias the\n` +
+    `// real runtime types so a global-built Cookie is exactly what Response.setCookie\n` +
+    `// / SecureCookies.seal expect. The toilscript compiler registers them itself.\n` +
+    `declare const SameSite: typeof import('toiljs/server/runtime/http/cookie').SameSite;\n` +
+    `type SameSite = import('toiljs/server/runtime/http/cookie').SameSite;\n` +
+    `declare const CookieEncoding: typeof import('toiljs/server/runtime/http/cookie').CookieEncoding;\n` +
+    `type CookieEncoding = import('toiljs/server/runtime/http/cookie').CookieEncoding;\n` +
+    `declare const CookiePrefix: typeof import('toiljs/server/runtime/http/cookie').CookiePrefix;\n` +
+    `type CookiePrefix = import('toiljs/server/runtime/http/cookie').CookiePrefix;\n` +
+    `declare const CookieValidation: typeof import('toiljs/server/runtime/http/cookie').CookieValidation;\n` +
+    `type CookieValidation = import('toiljs/server/runtime/http/cookie').CookieValidation;\n` +
+    `declare const Cookie: typeof import('toiljs/server/runtime/http/cookie').Cookie;\n` +
+    `type Cookie = import('toiljs/server/runtime/http/cookie').Cookie;\n` +
+    `declare const CookieMap: typeof import('toiljs/server/runtime/http/cookies').CookieMap;\n` +
+    `type CookieMap = import('toiljs/server/runtime/http/cookies').CookieMap;\n` +
+    `declare const Cookies: typeof import('toiljs/server/runtime/http/cookies').Cookies;\n` +
+    `type Cookies = import('toiljs/server/runtime/http/cookies').Cookies;\n` +
+    `declare const SecureCookies: typeof import('toiljs/server/runtime/http/securecookies').SecureCookies;\n` +
+    `type SecureCookies = import('toiljs/server/runtime/http/securecookies').SecureCookies;\n`;
+
 /**
  * Returns a `./`-prefixed, **extensionless** POSIX module specifier from `.toil` to `abs`, for use
  * in generated `import(...)` calls. Extensionless so TypeScript doesn't demand

package/src/compiler/index.ts

@@ -12,7 +12,7 @@ import { build as viteBuild, createServer, mergeConfig, type ViteDevServer } fro
 import type { RunningBackend } from 'toiljs/backend';
 
 import { loadConfig } from './config.js';
-import { generate } from './generate.js';
+import { generate, TOIL_SERVER_ENV_DTS } from './generate.js';
 import { prerenderStaticParams } from './ssg.js';
 import { extractTemplates } from './template-build.js';
 import { createViteConfig } from './vite.js';
@@ -109,6 +109,19 @@ function serverEntryFiles(root: string): string[] {
 async function buildServer(root: string): Promise<void> {
     if (!fs.existsSync(path.join(root, 'toilconfig.json'))) return;
 
+    // Regenerate the editor-only server-globals d.ts each build (the same way
+    // `generate` rewrites `toil-env.d.ts`), so an existing project auto-migrates
+    // to the current shapes without re-scaffolding or running doctor. Best
+    // effort; an unwritable dir never blocks the build.
+    for (const dir of serverDirs(root)) {
+        try {
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(path.join(dir, 'toil-server-env.d.ts'), TOIL_SERVER_ENV_DTS);
+        } catch {
+            // editor-only; ignore write failures
+        }
+    }
+
     const require = createRequire(path.join(root, 'package.json'));
     let binJs: string;
     try {
@@ -337,7 +350,7 @@ export async function start(opts: ToilCommandOptions = {}): Promise<RunningBacke
 export { defineConfig, loadConfig, AiProvider } from './config.js';
 export { scanRoutes } from './routes.js';
 export type { ScannedRoute } from './routes.js';
-export { TOIL_ENV_DTS } from './generate.js';
+export { TOIL_ENV_DTS, TOIL_SERVER_ENV_DTS } from './generate.js';
 export { AI_HELPERS, AI_HELPER_IDS, aiHelperFiles, TOIL_DOCS } from './docs.js';
 export type { AiHelper } from './docs.js';
 export type {

package/examples/basic/server/toil-server-env.d.ts

@@ -1,94 +0,0 @@
-/**
- * Editor-only ambient declarations for the toiljs cookie globals.
- *
- * `Cookie`, `Cookies`, `SecureCookies`, and the `SameSite` / `CookieEncoding` /
- * `CookiePrefix` enums are `@global` in the toiljs server runtime, so a handler
- * uses them with no import (exactly like `crypto`). The toilscript compiler
- * registers them from the runtime; this file just gives the editor their shapes
- * so it does not flag the unimported names. It is auto-included by the server
- * `tsconfig.json` (`include: ["./**/*.ts"]`) and ignored by the compiler.
- *
- * `toiljs create` scaffolds this file; keep it in sync with
- * `toiljs/server/runtime/http/*`.
- */
-
-declare enum SameSite {
-    Default = 0,
-    None = 1,
-    Lax = 2,
-    Strict = 3,
-}
-
-declare enum CookieEncoding {
-    Percent = 0,
-    Raw = 1,
-    Base64Url = 2,
-}
-
-declare enum CookiePrefix {
-    None = 0,
-    Secure = 1,
-    Host = 2,
-}
-
-declare class CookieValidation {
-    valid: bool;
-    errors: Array<string>;
-    fail(msg: string): void;
-}
-
-declare class Cookie {
-    name: string;
-    value: string;
-    encoding: CookieEncoding;
-    constructor(name: string, value: string);
-    static create(name: string, value: string): Cookie;
-    domain(v: string): Cookie;
-    path(v: string): Cookie;
-    maxAge(seconds: i64): Cookie;
-    expires(epochSeconds: i64): Cookie;
-    expiresRaw(date: string): Cookie;
-    secure(on?: bool): Cookie;
-    httpOnly(on?: bool): Cookie;
-    sameSite(s: SameSite): Cookie;
-    partitioned(on?: bool): Cookie;
-    priority(p: string): Cookie;
-    extension(av: string): Cookie;
-    withEncoding(e: CookieEncoding): Cookie;
-    asSecurePrefixed(): Cookie;
-    asHostPrefixed(): Cookie;
-    detectedPrefix(): CookiePrefix;
-    encodedValue(): string;
-    validate(): CookieValidation;
-    serialize(strict?: bool): string;
-    toString(): string;
-}
-
-declare class CookieMap {
-    set(name: string, value: string): void;
-    get(name: string): string | null;
-    has(name: string): bool;
-    names(): Array<string>;
-    readonly size: i32;
-}
-
-declare class Cookies {
-    static parse(cookieHeader: string): CookieMap;
-    static get(cookieHeader: string, name: string): string | null;
-    static serialize(name: string, value: string): string;
-    static parseSetCookie(setCookie: string): Cookie;
-    static encodeValue(raw: string): string;
-    static decodeValue(enc: string): string;
-}
-
-declare class SecureCookies {
-    static signed(key: Uint8Array): SecureCookies;
-    static encrypted(key: Uint8Array): SecureCookies;
-    addKey(key: Uint8Array): SecureCookies;
-    sign(name: string, value: string): string;
-    unsign(name: string, sealed: string): string | null;
-    encrypt(name: string, value: string): string;
-    decrypt(name: string, sealed: string): string | null;
-    seal(cookie: Cookie): Cookie;
-    open(jar: CookieMap, name: string): string | null;
-}