@distilled.cloud/core 0.30.3 → 1.0.0-rc.2

package/lib/codegen/emit.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The PURE annotation emitted before generated schema consts. A single
+ * `/*@__PURE__*​/` — Rolldown 1.1+ warns on the `/*#__PURE__*​/` form
+ * (distilled #374).
+ */
+export declare const PURE = "/*@__PURE__*/ ";
+/** `export interface X { … }` (or the empty-body form). */
+export declare const interfaceDecl: (name: string, fields: string[]) => string;
+export interface SuspendConstOptions {
+    readonly name: string;
+    /** The schema expression inside the suspend thunk. */
+    readonly expr: string;
+    /** PURE marker(s), e.g. `"/*@__PURE__*​/ "`. Emitted verbatim before the expression. */
+    readonly pure?: string;
+    /** When set, `.annotate({ identifier: <name> })` is appended after the suspend. */
+    readonly annotateIdentifier?: boolean;
+    /** Extra annotation object source to use instead of the identifier default. */
+    readonly annotation?: string;
+    /**
+     * Explicit thunk return type (`(): S.Schema<X> =>`) — used for shapes in
+     * dependency cycles to stop circular type inference.
+     */
+    readonly thunkType?: string;
+    /** CF-style multiline body (`S.suspend(() =>\n<expr>,\n)`). */
+    readonly multiline?: boolean;
+    /** The cast target; defaults to `S.Schema<name>`. */
+    readonly castTo?: string;
+}
+/**
+ * The `export const X = S.suspend(…) … as any as S.Schema<X>;` skeleton
+ * shared by both generators.
+ */
+export declare const suspendConst: (o: SuspendConstOptions) => string;
+/**
+ * Member-level lazy reference: `S.suspend(() => X).annotate({ identifier })`.
+ * The `typed` form adds an explicit `S.Schema<X>` thunk return type — used
+ * for references into dependency cycles to stop circular type inference.
+ */
+export declare const suspendRef: (name: string, typed?: boolean) => string;
+export interface EnumDeclOptions {
+    readonly name: string;
+    readonly values: readonly string[];
+    readonly pure?: string;
+    /** The schema const expression; both SDKs use `S.String` (open enums). */
+    readonly schemaExpr?: string;
+}
+/**
+ * String-union enum ALIAS: the spec's documented values as a CLOSED literal
+ * union (`type X = "a" | "b"`) — response readers match documented values
+ * exhaustively. INPUT references re-open the alias inline
+ * (`X | (string & {})`) so consumers can send tomorrow's values without an
+ * SDK update. The schema stays `S.String` in both directions (the
+ * protocols never validate enum membership, so undocumented wire values
+ * always pass through at runtime).
+ */
+export declare const enumDecl: (o: EnumDeclOptions) => string[];
+export interface ErrorClassOptions {
+    readonly name: string;
+    /** The error tag; defaults to `name`. */
+    readonly tag?: string;
+    /** Field lines (`  key: S.String,`). */
+    readonly fields: readonly string[];
+    /** Optional extra argument(s) after the fields object (annotations). */
+    readonly annotations?: string;
+    /** `.pipe(…)` suffix (e.g. category decorators). */
+    readonly pipes?: string;
+    /** Wrap the class expression (e.g. `T.applyErrorMatchers(<cls>, …)`). */
+    readonly wrap?: (cls: string) => string;
+}
+/**
+ * `export class X extends /*@__PURE__*​/ S.TaggedErrorClass<X>()("X", { … }) {}`
+ *
+ * The PURE markers are what make an unused error class droppable. A class
+ * whose heritage clause is an unannotated call can never be tree-shaken —
+ * the bundler has to assume the call has side effects — so a consumer
+ * importing one operation would retain every error class in the module
+ * (distilled #191).
+ *
+ * `wrap` needs its own marker as well as the inner one: a pure call's
+ * ARGUMENTS are still evaluated, so annotating only
+ * `T.applyErrorMatchers(S.TaggedErrorClass…(…), […])` leaves the inner call
+ * holding the class alive. Verified against esbuild in both directions.
+ */
+export declare const errorClass: (o: ErrorClassOptions) => string;
+export interface OperationConstOptions {
+    /** The exported (usually lowerFirst) operation name. */
+    readonly exportName: string;
+    /** Full type annotation (e.g. `API.OperationMethod<A, B, E, R>`). */
+    readonly typeAnnotation: string;
+    /** `API.make` or `API.makePaginated` (with namespace prefix). */
+    readonly factory: string;
+    /** The config object source (including braces). */
+    readonly config: string;
+    /** Optional extra factory argument (e.g. a pagination strategy). */
+    readonly extraArg?: string;
+    readonly pure?: string;
+    /**
+     * Widen the factory result to `any`, for annotations the factory's
+     * generic signature can't prove. The one case today: a paginated
+     * operation's `items` element type comes from the pagination trait's
+     * `items` PATH — a runtime string — so the factory can only infer the
+     * structural fallback while the annotation names the real element type.
+     *
+     * Unlike the schema consts' `as any as S.Schema<X>`, the target doesn't
+     * need restating here: the const carries its own annotation, which IS
+     * the assignment target, so a bare `as any` lands in the same place.
+     * Restating it would double every paginated operation's declaration —
+     * ~40k lines across the SDKs — for no added checking.
+     */
+    readonly castToAnnotation?: boolean;
+}
+/** `export const op: T = API.make(() => ({ … }));` */
+export declare const operationConst: (o: OperationConstOptions) => string;
+export interface InterfaceFieldOptions {
+    readonly name: string;
+    readonly type: string;
+    readonly optional: boolean;
+    readonly doc?: string;
+}
+/** Interface field line(s): optional doc comment + `  name?: Type;`. */
+export declare const interfaceField: (o: InterfaceFieldOptions) => string[];
+/** `export type <Op>Error = A | B | <CommonErrors>;` */
+export declare const errorUnionAlias: (opName: string, errorNames: readonly string[], commonRef: string) => string;
+/** Namespaced barrel: `export * as name from "./file.ts";` per entry. */
+export declare const barrel: (header: string, entries: ReadonlyArray<{
+    name: string;
+    path: string;
+}>) => string;
+//# sourceMappingURL=emit.d.ts.map

package/lib/codegen/emit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/codegen/emit.ts"],"names":[],"mappings":"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"}

package/lib/codegen/emit.js

@@ -0,0 +1,105 @@
+/**
+ * Shared emission idioms for the SDK generators (dev-time only).
+ *
+ * Both SDK generators emit the same compile-time-performance pattern
+ * (ported from distilled PR #360):
+ *
+ *   export interface X { … }                      // hand-emitted type
+ *   export const X = S.suspend(() => S.Struct({…}))
+ *     .annotate({ identifier: "X" })
+ *     as any as S.Schema<X>;                      // no inference needed
+ *
+ * plus closed-alias string-union enums, `S.TaggedErrorClass` error classes, and
+ * `API.make(() => ({ … }))` operation consts. The helpers here own those
+ * shared skeletons; providers own the content strings (member pipes, trait
+ * calls, config fields). Emitted output is normalized by oxfmt afterwards,
+ * so helpers emit canonical token streams rather than matching historical
+ * whitespace.
+ */
+import { q } from "./naming.js";
+/**
+ * The PURE annotation emitted before generated schema consts. A single
+ * `/*@__PURE__*​/` — Rolldown 1.1+ warns on the `/*#__PURE__*​/` form
+ * (distilled #374).
+ */
+export const PURE = "/*@__PURE__*/ ";
+/** `export interface X { … }` (or the empty-body form). */
+export const interfaceDecl = (name, fields) => fields.length
+    ? `export interface ${name} {\n${fields.join("\n")}\n}`
+    : `export interface ${name} {}`;
+/**
+ * The `export const X = S.suspend(…) … as any as S.Schema<X>;` skeleton
+ * shared by both generators.
+ */
+export const suspendConst = (o) => {
+    const cast = o.castTo ?? `S.Schema<${o.name}>`;
+    const thunk = o.thunkType ? `(): ${o.thunkType} =>` : `() =>`;
+    const suspend = o.multiline
+        ? `S.suspend(${thunk}\n${o.expr},\n)`
+        : `S.suspend(${thunk} ${o.expr})`;
+    const annotate = o.annotation
+        ? `.annotate(${o.annotation})`
+        : o.annotateIdentifier
+            ? `.annotate({ identifier: ${q(o.name)} })`
+            : "";
+    return `export const ${o.name} = ${o.pure ?? ""}${suspend}${annotate} as any as ${cast};\n`;
+};
+/**
+ * Member-level lazy reference: `S.suspend(() => X).annotate({ identifier })`.
+ * The `typed` form adds an explicit `S.Schema<X>` thunk return type — used
+ * for references into dependency cycles to stop circular type inference.
+ */
+export const suspendRef = (name, typed = false) => typed
+    ? `S.suspend((): S.Schema<${name}> => ${name}).annotate({ identifier: ${q(name)} })`
+    : `S.suspend(() => ${name}).annotate({ identifier: ${q(name)} })`;
+/**
+ * String-union enum ALIAS: the spec's documented values as a CLOSED literal
+ * union (`type X = "a" | "b"`) — response readers match documented values
+ * exhaustively. INPUT references re-open the alias inline
+ * (`X | (string & {})`) so consumers can send tomorrow's values without an
+ * SDK update. The schema stays `S.String` in both directions (the
+ * protocols never validate enum membership, so undocumented wire values
+ * always pass through at runtime).
+ */
+export const enumDecl = (o) => {
+    const union = o.values.length ? o.values.map(q).join(" | ") : "string";
+    return [
+        `export type ${o.name} = ${union};`,
+        `export const ${o.name} = ${o.pure ?? ""}${o.schemaExpr ?? "S.String"};\n`,
+    ];
+};
+/**
+ * `export class X extends /*@__PURE__*​/ S.TaggedErrorClass<X>()("X", { … }) {}`
+ *
+ * The PURE markers are what make an unused error class droppable. A class
+ * whose heritage clause is an unannotated call can never be tree-shaken —
+ * the bundler has to assume the call has side effects — so a consumer
+ * importing one operation would retain every error class in the module
+ * (distilled #191).
+ *
+ * `wrap` needs its own marker as well as the inner one: a pure call's
+ * ARGUMENTS are still evaluated, so annotating only
+ * `T.applyErrorMatchers(S.TaggedErrorClass…(…), […])` leaves the inner call
+ * holding the class alive. Verified against esbuild in both directions.
+ */
+export const errorClass = (o) => {
+    const annotations = o.annotations ? `,\n${o.annotations}` : "";
+    const cls = `${PURE}S.TaggedErrorClass<${o.name}>()(${q(o.tag ?? o.name)}, {\n${o.fields.join("\n")}\n}${annotations})${o.pipes ?? ""}`;
+    const body = o.wrap ? `${PURE}${o.wrap(cls)}` : cls;
+    return `export class ${o.name} extends ${body} {}\n`;
+};
+/** `export const op: T = API.make(() => ({ … }));` */
+export const operationConst = (o) => `export const ${o.exportName}: ${o.typeAnnotation} = ${o.pure ?? ""}${o.factory}(() => (${o.config})${o.extraArg ? `, ${o.extraArg}` : ""})${o.castToAnnotation ? ` as any` : ""};\n`;
+import { tsKey } from "./naming.js";
+/** Interface field line(s): optional doc comment + `  name?: Type;`. */
+export const interfaceField = (o) => [
+    ...(o.doc ? [`  /** ${o.doc} */`] : []),
+    `  ${tsKey(o.name)}${o.optional ? "?" : ""}: ${o.type};`,
+];
+/** `export type <Op>Error = A | B | <CommonErrors>;` */
+export const errorUnionAlias = (opName, errorNames, commonRef) => `export type ${opName}Error = ${[...errorNames, commonRef].join(" | ")};`;
+/** Namespaced barrel: `export * as name from "./file.ts";` per entry. */
+export const barrel = (header, entries) => header +
+    entries.map((e) => `export * as ${e.name} from ${q(e.path)};`).join("\n") +
+    "\n";
+//# sourceMappingURL=emit.js.map

package/lib/codegen/emit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.js","sourceRoot":"","sources":["../../src/codegen/emit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,aAAa,CAAC;AAEhC;;;;GAIG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,gBAAgB,CAAC;AAErC,2DAA2D;AAC3D,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAY,EAAE,MAAgB,EAAU,EAAE,CACtE,MAAM,CAAC,MAAM;IACX,CAAC,CAAC,oBAAoB,IAAI,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;IACvD,CAAC,CAAC,oBAAoB,IAAI,KAAK,CAAC;AAuBpC;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAsB,EAAU,EAAE;IAC7D,MAAM,IAAI,GAAG,CAAC,CAAC,MAAM,IAAI,YAAY,CAAC,CAAC,IAAI,GAAG,CAAC;IAC/C,MAAM,KAAK,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC;IAC9D,MAAM,OAAO,GAAG,CAAC,CAAC,SAAS;QACzB,CAAC,CAAC,aAAa,KAAK,KAAK,CAAC,CAAC,IAAI,MAAM;QACrC,CAAC,CAAC,aAAa,KAAK,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC;IACpC,MAAM,QAAQ,GAAG,CAAC,CAAC,UAAU;QAC3B,CAAC,CAAC,aAAa,CAAC,CAAC,UAAU,GAAG;QAC9B,CAAC,CAAC,CAAC,CAAC,kBAAkB;YACpB,CAAC,CAAC,2BAA2B,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK;YAC3C,CAAC,CAAC,EAAE,CAAC;IACT,OAAO,gBAAgB,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,IAAI,IAAI,EAAE,GAAG,OAAO,GAAG,QAAQ,cAAc,IAAI,KAAK,CAAC;AAC9F,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAY,EAAE,KAAK,GAAG,KAAK,EAAU,EAAE,CAChE,KAAK;IACH,CAAC,CAAC,0BAA0B,IAAI,QAAQ,IAAI,4BAA4B,CAAC,CAAC,IAAI,CAAC,KAAK;IACpF,CAAC,CAAC,mBAAmB,IAAI,4BAA4B,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;AAUtE;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAkB,EAAY,EAAE;IACvD,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IACvE,OAAO;QACL,eAAe,CAAC,CAAC,IAAI,MAAM,KAAK,GAAG;QACnC,gBAAgB,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,IAAI,IAAI,EAAE,GAAG,CAAC,CAAC,UAAU,IAAI,UAAU,KAAK;KAC3E,CAAC;AACJ,CAAC,CAAC;AAgBF;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAoB,EAAU,EAAE;IACzD,MAAM,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/D,MAAM,GAAG,GAAG,GAAG,IAAI,sBAAsB,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,WAAW,IAAI,CAAC,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;IACxI,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;IACpD,OAAO,gBAAgB,CAAC,CAAC,IAAI,YAAY,IAAI,OAAO,CAAC;AACvD,CAAC,CAAC;AA8BF,sDAAsD;AACtD,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAwB,EAAU,EAAE,CACjE,gBAAgB,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,cAAc,MAAM,CAAC,CAAC,IAAI,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,IAChG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EACnC,IAAI,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC;AAE/C,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AASpC,wEAAwE;AACxE,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAwB,EAAY,EAAE,CAAC;IACpE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACvC,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,GAAG;CACzD,CAAC;AAEF,wDAAwD;AACxD,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,MAAc,EACd,UAA6B,EAC7B,SAAiB,EACT,EAAE,CACV,eAAe,MAAM,WAAW,CAAC,GAAG,UAAU,EAAE,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC;AAE5E,yEAAyE;AACzE,MAAM,CAAC,MAAM,MAAM,GAAG,CACpB,MAAc,EACd,OAAsD,EAC9C,EAAE,CACV,MAAM;IACN,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;IACzE,IAAI,CAAC"}

package/lib/codegen/format.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Post-generation formatting (dev-time only).
+ *
+ * The emitters produce a canonical token stream, not formatted source, so
+ * every generator formats what it wrote before finishing. Without it a
+ * generate run leaves the whole output directory dirty against the committed
+ * (formatted) files, and a real regression is indistinguishable from
+ * whitespace in the diff.
+ *
+ * Lives here so the shared {@link runGeneratorCli} and the providers with
+ * their own pipelines run the identical step.
+ */
+import { Effect } from "effect";
+/** Run a dev-time tool, failing the generate run if it does. */
+export declare const runTool: (argv: readonly string[]) => Effect.Effect<void, never, never>;
+/** Format a generated directory in place. */
+export declare const formatGenerated: (dir: string) => Effect.Effect<void, never, never>;
+/**
+ * Lint-fix then format. `oxlint --fix` can leave its rewrites unformatted,
+ * so the formatter has to run after it, not before.
+ */
+export declare const lintAndFormatGenerated: (dir: string) => Effect.Effect<void, never, never>;
+//# sourceMappingURL=format.d.ts.map

package/lib/codegen/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/codegen/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAW,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEzC,gEAAgE;AAChE,eAAO,MAAM,OAAO,SACZ,SAAS,MAAM,EAAE,KACtB,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAYhC,CAAC;AAEJ,6CAA6C;AAC7C,eAAO,MAAM,eAAe,QAAS,MAAM,sCAGxC,CAAC;AAEJ;;;GAGG;AACH,eAAO,MAAM,sBAAsB,QAAS,MAAM,sCAK/C,CAAC"}

package/lib/codegen/format.js

@@ -0,0 +1,28 @@
+/**
+ * Post-generation formatting (dev-time only).
+ *
+ * The emitters produce a canonical token stream, not formatted source, so
+ * every generator formats what it wrote before finishing. Without it a
+ * generate run leaves the whole output directory dirty against the committed
+ * (formatted) files, and a real regression is indistinguishable from
+ * whitespace in the diff.
+ *
+ * Lives here so the shared {@link runGeneratorCli} and the providers with
+ * their own pipelines run the identical step.
+ */
+import { Console, Effect } from "effect";
+/** Run a dev-time tool, failing the generate run if it does. */
+export const runTool = (argv) => Effect.tryPromise({
+    try: () => Bun.spawn([...argv], { stdout: "inherit", stderr: "inherit" }).exited,
+    catch: (cause) => new Error(`${argv[0]} failed to start: ${cause}`),
+}).pipe(Effect.flatMap((code) => code === 0
+    ? Effect.void
+    : Effect.die(new Error(`${argv.join(" ")} exited with ${code}`))), Effect.catchCause((cause) => Effect.die(cause)));
+/** Format a generated directory in place. */
+export const formatGenerated = (dir) => Effect.flatMap(Console.log(`\n🧹 Formatting ${dir}`), () => runTool(["bunx", "oxfmt", dir]));
+/**
+ * Lint-fix then format. `oxlint --fix` can leave its rewrites unformatted,
+ * so the formatter has to run after it, not before.
+ */
+export const lintAndFormatGenerated = (dir) => Effect.flatMap(Console.log(`\n🧹 Linting and formatting ${dir}`), () => Effect.flatMap(runTool(["bunx", "oxlint", "--fix", dir]), () => runTool(["bunx", "oxfmt", dir])));
+//# sourceMappingURL=format.js.map

package/lib/codegen/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/codegen/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEzC,gEAAgE;AAChE,MAAM,CAAC,MAAM,OAAO,GAAG,CACrB,IAAuB,EACY,EAAE,CACrC,MAAM,CAAC,UAAU,CAAC;IAChB,GAAG,EAAE,GAAG,EAAE,CACR,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,MAAM;IACvE,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,qBAAqB,KAAK,EAAE,CAAC;CACpE,CAAC,CAAC,IAAI,CACL,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CACtB,IAAI,KAAK,CAAC;IACR,CAAC,CAAC,MAAM,CAAC,IAAI;IACb,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,IAAI,EAAE,CAAC,CAAC,CACnE,EACD,MAAM,CAAC,UAAU,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAChD,CAAC;AAEJ,6CAA6C;AAC7C,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,GAAW,EAAE,EAAE,CAC7C,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CACzD,OAAO,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC,CAChC,CAAC;AAEJ;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,GAAW,EAAE,EAAE,CACpD,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,+BAA+B,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CACrE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,CAC7D,OAAO,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC,CAChC,CACF,CAAC"}

package/lib/codegen/generator.d.ts

@@ -0,0 +1,334 @@
+/**
+ * The generic smithy→SDK service generator (dev-time only).
+ *
+ * One driver compiles a Smithy JSON model into an Effect SDK service module.
+ * Everything provider-specific arrives through {@link SdkSpec}: import
+ * header, trait vocabulary (which trait ids mean payload/file/nullable/…),
+ * the `T.*` pipe expressions to emit for each binding, how operations are
+ * declared (protocol/retry/error names), and naming policies. The driver
+ * owns the pipeline: operation discovery, reachability, topological order,
+ * schema/interface emission, error classes, pagination validation, and
+ * operation consts.
+ *
+ * A provider's `scripts/generate.ts` reduces to: load models (its own
+ * pipeline — docs-derived specs, patches, …), define its {@link SdkSpec},
+ * call {@link generateService} per model, write files.
+ */
+import { local, q, tsKey, upperFirst } from "./naming.ts";
+import { type ShapeMap } from "./graph.ts";
+import { errorUnionAlias, operationConst } from "./emit.ts";
+import { type OpEntry } from "./operations.ts";
+/**
+ * Error categories, derived from the STANDARD Smithy error traits.
+ *
+ * `smithy.api#httpError` and `smithy.api#retryable` are how every Smithy
+ * model — AWS's included — says what kind of failure an error is. The
+ * categories the runtime acts on (`core/category.ts`, and `isTransientError`
+ * in `core/retry.ts`) are a reading of those two traits, so the reading
+ * belongs here, once, for every provider.
+ *
+ * A model that wants its errors classified states the status the API
+ * actually returns:
+ *
+ *   "traits": { "smithy.api#error": "client", "smithy.api#httpError": 404 }
+ *
+ * and the error class is emitted with `.pipe(C.withNotFoundError)`. A model
+ * with no `httpError` gets no categories — the same as today.
+ */
+export declare const errorCategories: (traits: Record<string, any> | undefined, 
+/** Categories a provider knows that the traits don't say (AWS's spec file). */
+extra?: readonly string[]) => string[];
+/** A member's resolved binding. The four generic kinds plus provider extras. */
+export type MemberBinding = "label" | "query" | "header" | "body" | (string & {});
+export interface EmittedMember {
+    readonly name: string;
+    readonly tsName: string;
+    readonly wire: string;
+    readonly target: string;
+    readonly binding: MemberBinding;
+    readonly required: boolean;
+    readonly nullable: boolean;
+    readonly doc: string | undefined;
+    readonly traits: Record<string, any>;
+}
+export interface PaginationProfile {
+    /** Protocol const for paginated ops. Defaults to operationDecl.protocol. */
+    readonly protocol?: string;
+    /** Strategy expression passed as makePaginated's second argument. */
+    readonly strategy?: string;
+    /** Items path fallback when the trait omits `items`. */
+    readonly itemsFallback: string;
+    /** Output names accepted even when not modeled (delivered by the protocol). */
+    readonly syntheticOutputs?: readonly string[];
+    /**
+     * Extra interface field + struct member appended to paginated outputs
+     * that don't already model them (what the protocol delivers beyond the
+     * modeled shape — e.g. cloudflare's `resultInfo` from the envelope's
+     * `result_info`). `imports` are pulled from the pagination module in the
+     * header.
+     */
+    readonly injectOutputMember?: {
+        readonly tsName: string;
+        readonly interfaceLines: readonly string[];
+        readonly structLine: string;
+        readonly imports?: readonly string[];
+    };
+}
+export interface OperationEmit {
+    readonly op: OpEntry;
+    readonly opName: string;
+    readonly exportName: string;
+    readonly inputName: string;
+    readonly outputName: string;
+    /**
+     * The output as a TS type and as a schema expression. These differ from
+     * {@link outputName} when the operation's output IS a prelude shape
+     * (e.g. stripe's freeform `smithy.api#Document` responses): the bare
+     * local name isn't declared in the module, so it must resolve through
+     * the prelude maps (`unknown` / `S.Unknown`) instead.
+     */
+    readonly outputTsType: string;
+    readonly outputSchema: string;
+    /** Declared error class names present in the model. */
+    readonly errorNames: readonly string[];
+    readonly doc: string | undefined;
+    /** The validated pagination trait, when the op paginates. */
+    readonly pagination: unknown | undefined;
+}
+export interface SdkSpec {
+    /** Namespace fallback for models with no operations. Default `"smithy.unknown"`. */
+    readonly namespaceFallback?: string;
+    /** PURE marker before schema consts. Default: the shared single marker. */
+    readonly pure?: string;
+    /** Prelude scalar → schema expression map. Default {@link JSON_PRELUDE}. */
+    readonly prelude?: Record<string, string>;
+    /** Prelude scalar → TS type map. Default {@link TS_JSON_PRELUDE}. */
+    readonly tsPrelude?: Record<string, string>;
+    /** Wire member name → TS-facing name. Default: identity. */
+    readonly memberName?: (name: string) => string;
+    /** Operation shape name → exported const name. Default: lowerFirst. */
+    readonly opExportName?: (name: string) => string;
+    /**
+     * Emit the one-line smithy doc comment above shapes and error classes.
+     * Default true. AWS turns this off — its models carry multi-kilobyte HTML
+     * docs per shape and the SDK only surfaces operation-level docs.
+     */
+    readonly shapeDocs?: boolean;
+    /**
+     * Extra reachability roots beyond the operations' I/O shapes. AWS seeds
+     * the error shapes here so their member targets are emitted (error class
+     * fields reference schema consts); the error shapes themselves are still
+     * emitted as error classes, not schemas.
+     */
+    readonly extraRoots?: (selected: readonly OpEntry[], shapes: ShapeMap) => Iterable<string>;
+    /**
+     * Provider member bindings as data, checked in order between the generic
+     * header binding and `smithy.api#httpPayload`. The driver's cascade:
+     * label → query → header → extraBindings → rawBody (httpPayload) → body.
+     *
+     * `pipe` is emitted for the member; `tsType` overrides its interface
+     * type (e.g. file uploads → `(File | Blob)[]`).
+     */
+    readonly extraBindings?: ReadonlyArray<{
+        readonly trait: string;
+        readonly binding: MemberBinding;
+        readonly pipe: string;
+        readonly tsType?: string;
+        /**
+         * Bare-payload form: when this binding is the sole member of a
+         * (non-paginated) output structure, the whole response IS that
+         * member's value — the driver emits the member's type directly and
+         * pipes the schema through this root marker for the protocol.
+         */
+        readonly rootPipe?: string;
+    }>;
+    /**
+     * Which wire-name rule a binding follows. Defaults: the three generic
+     * kinds map to themselves, everything else to `"other"` (jsonName).
+     */
+    readonly wireKind?: (binding: MemberBinding) => "label" | "query" | "header" | "other";
+    /** Trait id marking a member nullable (`S.NullOr` + `| null`). */
+    readonly nullableTrait?: string;
+    /**
+     * Blanket-nullable optionals: every optional body member types and
+     * decodes as `X | null` in addition to being omittable (`?: X | null`,
+     * `S.optional(S.NullOr(X))`). The cloudflare docs pipeline sets this —
+     * the v4 API freely returns explicit nulls for absent optional fields,
+     * and the v0 SDK surface modeled every optional that way.
+     */
+    readonly optionalsNullable?: boolean;
+    /**
+     * Member traits emitted as pipes when present: trait id → pipe builder
+     * name in the SDK's traits module. The trait's value is JSON-inlined as
+     * the argument (e.g. `"…#keyDictionary": "T.KeyDictionary"` →
+     * `T.KeyDictionary({…})`).
+     */
+    readonly memberTraitPipes?: Readonly<Record<string, string>>;
+    /**
+     * Extra schema pipes appended after the generic ones, for anything the
+     * data tables can't express. The driver emits `T.Label/T.Query/T.Header`
+     * (wire-aware), `T.HttpBody()` for rawBody, and `T.Body(wire)` renames —
+     * the SDK's traits module must export those core builders under these
+     * names.
+     */
+    readonly memberExtraPipes?: (m: EmittedMember) => string[];
+    /** Full override of member pipe emission (rarely needed). */
+    readonly memberPipes?: (m: EmittedMember) => string[];
+    /** Function override for member TS types beyond the binding table. */
+    readonly memberTsType?: (m: EmittedMember, tsRef: (target: string) => string) => string | undefined;
+    /**
+     * Struct-level pipes for a shape (after the member struct): the http
+     * trait on op inputs, service-wide key-dictionary stamping, etc.
+     */
+    readonly structPipes?: (ctx: {
+        readonly id: string;
+        readonly isOpIo: boolean;
+        readonly httpTrait: unknown | undefined;
+    }) => string[];
+    /**
+     * Pagination profiles. A profile is the codegen-side description of one
+     * paginated wire variant: the Protocol const that decodes it, the
+     * strategy passed to makePaginated, the trait-validation rules, and any
+     * output member the protocol delivers beyond the modeled shape. SDKs
+     * with several pagination styles declare several profiles and select
+     * per-op via {@link SdkSpec.paginationProfileFor}.
+     */
+    readonly paginationProfiles?: Readonly<Record<string, PaginationProfile>>;
+    /**
+     * Select the profile for a paginated op (from its `smithy.api#paginated`
+     * trait / shape). Default: the sole declared profile; with several
+     * profiles this becomes required for ops to paginate.
+     */
+    readonly paginationProfileFor?: (trait: any, op: OpEntry) => string | undefined;
+    /**
+     * Service-wide fallback key dictionary stamped on op I/O roots (emitted
+     * as a `KEY_DICTIONARY` header const + `T.KeyDictionary(KEY_DICTIONARY)`
+     * root pipe). `doc` is the const's doc comment. An entry may list several
+     * wire spellings (first = canonical encode name; decode accepts all).
+     */
+    readonly rootKeyDictionary?: {
+        readonly dict: Record<string, string | ReadonlyArray<string>>;
+        readonly doc: string;
+    };
+    /** Banner suffix: `AUTO-GENERATED by scripts/generate.ts from <note>`. */
+    readonly sourceNote?: string;
+    /**
+     * Operation aliases: re-export the canonical op (and its
+     * Request/Response/Error types) under each alias name. Skipped when the
+     * target wasn't emitted or the alias name is taken.
+     */
+    readonly opAliases?: ReadonlyArray<{
+        readonly alias: string;
+        readonly target: string;
+    }>;
+    /**
+     * Full shape-emission override, checked before the driver's own shape
+     * handling. Return the emitted lines to own a shape (e.g. AWS's
+     * newtypes, structural unions, event streams), or undefined to let the
+     * driver emit it. `selfIdx` is the shape's position in emission order
+     * for forward-ref decisions.
+     */
+    readonly shapeOverride?: (ctx: {
+        readonly id: string;
+        readonly def: any;
+        readonly name: string;
+        readonly selfIdx: number;
+        readonly ref: (target: string, selfIdx: number) => string;
+        readonly tsRef: (target: string) => string;
+        readonly members: (d: any) => EmittedMember[];
+    }) => string[] | undefined;
+    /**
+     * Union emission style. `"opaque-cases"`: the TS type is the case union
+     * and the schema is `S.Unknown.pipe(T.UnionCases([...case key sets]))` —
+     * the protocol discriminates by key-set at decode time (for APIs that
+     * return every case's keys with nulls, like Cloudflare's).
+     */
+    readonly unionStyle?: "opaque-cases";
+    /** Full override of union emission. */
+    readonly union?: (ctx: {
+        readonly name: string;
+        readonly caseTargets: readonly string[];
+        readonly caseKeys: readonly (readonly string[])[];
+        readonly tsRef: (target: string) => string;
+    }) => string[];
+    /**
+     * Trait id carrying error matchers: when present on an error shape, the
+     * class is wrapped in `T.applyErrorMatchers(<cls>, <trait value>)`.
+     */
+    readonly errorMatchersTrait?: string;
+    /** Error-class emission details. All optional. */
+    readonly errors?: {
+        /**
+         * Full override of one error class's emission (mirrors shapeOverride):
+         * return the emitted lines to own the error, or undefined to fall back
+         * to the driver's field/wrap-based emission.
+         */
+        readonly override?: (ctx: {
+            readonly id: string;
+            readonly def: any;
+            readonly name: string;
+        }) => string[] | undefined;
+        /**
+         * Field lines used when the error shape declares no members.
+         * Default: `code` (integer) + `message` (string) — the common REST
+         * error envelope.
+         */
+        readonly defaultFields?: (prelude: Record<string, string>) => string[];
+        /** Field line for a declared member. Default: prelude-mapped schema. */
+        readonly field?: (name: string, target: string) => string;
+        /** Optional wrapper (e.g. matcher application) from the shape's traits. */
+        readonly wrap?: (traits: Record<string, any>) => ((cls: string) => string) | undefined;
+    };
+    /**
+     * Declarative operation emission — the names the op consts are built
+     * from. `operation` overrides this entirely when a provider needs full
+     * control of the emitted shape.
+     */
+    readonly operationDecl?: {
+        /** Requirements type in the OperationMethod annotation. */
+        readonly contextType: string;
+        /** Base of the per-op error union alias (e.g. `CloudflareOpError`). */
+        readonly commonErrorType: string;
+        /** Error classes appended to every op's `errors: [...]` list. */
+        readonly commonErrorClasses: readonly string[];
+        readonly protocol: string;
+        /** The retry tag expression (e.g. `Retry.Retry`). */
+        readonly retry: string;
+        /**
+         * Extra config lines inserted before the pagination entry (e.g. AWS's
+         * `operationName` and `endpointHostPrefix`).
+         */
+        readonly extraConfig?: (ctx: OperationEmit) => string[];
+    };
+    /** Full override of operation const emission. */
+    readonly operation?: (ctx: OperationEmit) => string;
+    /**
+     * Module header override. The default builds the banner + imports from
+     * {@link SdkSpec.operationDecl} names and the conventional module layout
+     * (`../traits.ts`, `../protocol.ts`, `../pagination.ts`, `../errors.ts`,
+     * `../retry.ts`), re-exports the op error/context types, and emits the
+     * `KEY_DICTIONARY` const when {@link SdkSpec.rootKeyDictionary} is set.
+     */
+    readonly header?: (ctx: {
+        readonly hasPaginated: boolean;
+        readonly model: any;
+    }) => string;
+    /** Final pass over the assembled module (e.g. pruning unused imports). */
+    readonly postProcess?: (code: string) => string;
+    /**
+     * Trailing sections after operations (e.g. route-alias re-exports).
+     * Receives the set of emitted op export names (mutable — additions are
+     * visible to subsequent alias checks).
+     */
+    readonly footer?: (ctx: {
+        readonly emittedOps: Set<string>;
+    }) => string[];
+}
+export interface GeneratedService {
+    code: string;
+    operations: number;
+}
+/** Compile one Smithy model into a service module. */
+export declare const generateService: (model: any, spec: SdkSpec) => GeneratedService;
+export { errorUnionAlias, operationConst, upperFirst, tsKey, q, local };
+//# sourceMappingURL=generator.d.ts.map