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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@distilled.cloud/core",
-  "version": "1.0.0-rc.2",
+  "version": "1.0.0-rc.4",
   "repository": {
     "type": "git",
     "url": "https://github.com/alchemy-run/distilled",
@@ -31,12 +31,12 @@
     "build": "tsc -b"
   },
   "devDependencies": {
-    "@effect/platform-bun": ">=4.0.0-beta.102 || >=4.0.0",
+    "@effect/platform-bun": ">=4.0.0-beta.104 || >=4.0.0",
     "@types/bun": "latest",
     "@types/node": "latest",
-    "effect": ">=4.0.0-beta.102 || >=4.0.0"
+    "effect": ">=4.0.0-beta.104 || >=4.0.0"
   },
   "peerDependencies": {
-    "effect": ">=4.0.0-beta.102 || >=4.0.0"
+    "effect": ">=4.0.0-beta.104 || >=4.0.0"
   }
 }

package/src/category.ts

@@ -9,7 +9,7 @@
  * ```ts
  * import * as Category from "@distilled.cloud/core/category";
  *
- * export class Unauthorized extends Schema.TaggedErrorClass<Unauthorized>()(
+ * export class Unauthorized extends Schema.TaggedError<Unauthorized>()(
  *   "Unauthorized",
  *   { message: Schema.String },
  * ).pipe(Category.withAuthError) {}
@@ -92,7 +92,7 @@ export interface RetryableInfo {
  *
  * @example
  * ```ts
- * export class MyError extends Schema.TaggedErrorClass<MyError>()(
+ * export class MyError extends Schema.TaggedError<MyError>()(
  *   "MyError",
  *   { message: Schema.String },
  * ).pipe(Category.withCategory(Category.AuthError)) {}
@@ -123,13 +123,13 @@ export const withCategory =
  * @example
  * ```ts
  * // Standard retryable error
- * export class TransientError extends Schema.TaggedErrorClass<TransientError>()(
+ * export class TransientError extends Schema.TaggedError<TransientError>()(
  *   "TransientError",
  *   { message: Schema.String },
  * ).pipe(Category.withRetryable()) {}
  *
  * // Throttling error (uses longer backoff)
- * export class RateLimitError extends Schema.TaggedErrorClass<RateLimitError>()(
+ * export class RateLimitError extends Schema.TaggedError<RateLimitError>()(
  *   "RateLimitError",
  *   { message: Schema.String },
  * ).pipe(Category.withRetryable({ throttling: true })) {}

package/src/codegen/cli.ts

@@ -37,6 +37,52 @@ export interface GeneratorCliOptions {
   readonly outDir?: string;
   /** Model files to skip (e.g. a shared protocols model). */
   readonly excludeModel?: (file: string) => boolean;
+  /**
+   * Where the models are, when they aren't a flat directory of `<resource>.json`.
+   * AWS vendors Amazon's own repo, whose models sit at
+   * `models/<service>/service/<version>/<service>-<version>.json`.
+   *
+   * Returns the model files to compile; manual specs are merged in after,
+   * as usual.
+   */
+  readonly discoverModels?: (ctx: {
+    readonly smithyDir: string;
+  }) => Effect.Effect<
+    ReadonlyArray<{ readonly file: string; readonly dir: string }>,
+    never,
+    FileSystem.FileSystem | Path.Path
+  >;
+  /**
+   * Side effects to run before generating — e.g. AWS copies `partitions.json`
+   * out of the smithy submodule, runtime data its endpoint resolver reads.
+   */
+  readonly prepare?: (ctx: {
+    readonly root: string;
+    readonly outDir: string;
+  }) => Effect.Effect<void, never, FileSystem.FileSystem | Path.Path>;
+  /**
+   * The output module's name, when it isn't the model's filename. AWS names
+   * modules after the service's `aws.api#service` sdkId (`amazon-s3.json` →
+   * `s3.ts`), so the public surface reads `AWS.S3.getObject`.
+   */
+  readonly resourceName?: (ctx: {
+    readonly model: any;
+    readonly file: string;
+  }) => string;
+  /** Barrel export name for a resource. Default: the resource name itself. */
+  readonly barrelExportName?: (resource: string) => string;
+  /**
+   * The closing pass over the output directory. Defaults to formatting;
+   * AWS lint-fixes first (see `codegen/format.ts`).
+   */
+  readonly finalize?: (dir: string) => Effect.Effect<void>;
+  /**
+   * Keep generating after a model fails, instead of stopping at the first.
+   * AWS compiles 430 services in one run, and one broken model shouldn't
+   * hide the state of the other 429. The run still FAILS at the end — the
+   * failures are reported together rather than swallowed.
+   */
+  readonly continueOnModelError?: boolean;
   /** Directory of hand-authored models merged after the generated ones. */
   readonly manualSpecsDir?: string;
   /** RFC-6902 patch chain root. Default `patches`; `false` disables. */
@@ -82,14 +128,19 @@ export const runGeneratorCli = (options: GeneratorCliOptions): void => {
         yield* Console.log(`   Smithy: ${smithyDir}`);
         yield* Console.log(`   Output: ${outDir}`);
 
+        yield* options.prepare?.({ root, outDir }) ?? Effect.void;
+
         // Generated models plus optional manual-specs (hand-authored models
         // for APIs the provider's spec source doesn't cover). A manual model
         // must not shadow a generated one.
-        const generated = (yield* fs.readDirectory(smithyDir))
-          .filter(
-            (f) => f.endsWith(".json") && !(options.excludeModel?.(f) ?? false),
-          )
-          .map((f) => ({ file: f, dir: smithyDir }));
+        const generated = options.discoverModels
+          ? yield* options.discoverModels({ smithyDir })
+          : (yield* fs.readDirectory(smithyDir))
+              .filter(
+                (f) =>
+                  f.endsWith(".json") && !(options.excludeModel?.(f) ?? false),
+              )
+              .map((f) => ({ file: f, dir: smithyDir }));
         const manualDir = options.manualSpecsDir
           ? path.resolve(root, options.manualSpecsDir)
           : undefined;
@@ -115,6 +166,7 @@ export const runGeneratorCli = (options: GeneratorCliOptions): void => {
         yield* fs.makeDirectory(outDir, { recursive: true });
 
         const written: string[] = [];
+        const failedModels: string[] = [];
         let totalOps = 0;
         let totalPatches = 0;
         let staleOps = 0;
@@ -140,12 +192,15 @@ export const runGeneratorCli = (options: GeneratorCliOptions): void => {
         }
 
         for (const { file, dir } of entries) {
-          const resource = file.replace(/\.json$/, "");
-          if (config.resource && resource !== config.resource) continue;
-
           const model = JSON.parse(
             yield* fs.readFileString(path.join(dir, file)),
           );
+          // The module's name — the model's filename unless the provider
+          // derives it from the model itself (AWS: the service's sdkId).
+          const resource =
+            options.resourceName?.({ model, file }) ??
+            file.replace(/\.json$/, "");
+          if (config.resource && resource !== config.resource) continue;
 
           // Apply the RFC-6902 patch chain before generating. Hand-written
           // *.manual.json patches apply after the generated ones — they
@@ -189,10 +244,22 @@ export const runGeneratorCli = (options: GeneratorCliOptions): void => {
             if (note) yield* Console.log(`   ${note}`);
           }
 
-          const { code, operations } = generateService(
-            model,
-            options.spec(model),
-          );
+          // `generateService` and the provider spec are synchronous and
+          // throw; with continueOnModelError the throw is recorded and the
+          // run moves on, so one broken model doesn't hide the state of
+          // every model after it. The run still fails at the end.
+          let generated;
+          try {
+            generated = generateService(model, options.spec(model));
+          } catch (e) {
+            if (!options.continueOnModelError) throw e;
+            failedModels.push(
+              `${resource}: ${e instanceof Error ? e.message : String(e)}`,
+            );
+            yield* Console.error(`❌ ${resource}`);
+            continue;
+          }
+          const { code, operations } = generated;
           if (operations === 0) continue;
 
           yield* fs.writeFileString(path.join(outDir, `${resource}.ts`), code);
@@ -224,11 +291,22 @@ export const runGeneratorCli = (options: GeneratorCliOptions): void => {
         // resource without removing anything.
         const barrelPath = path.join(outDir, "index.ts");
         const filtered = config.resource !== "";
-        let resources = written;
+        // Sorted, not in generation order: a provider that discovers models
+        // in some other order (AWS walks Amazon's directory tree) would
+        // otherwise reshuffle the barrel on every run.
+        let resources = [...written].sort((a, b) =>
+          `${a}.json`.localeCompare(`${b}.json`),
+        );
         if (filtered && (yield* fs.exists(barrelPath))) {
+          // Recover the RESOURCE from each export line's path, not its name:
+          // the two differ when barrelExportName renames (AWS exports
+          // `S3` from `./s3.ts`).
           const existing = (yield* fs.readFileString(barrelPath))
             .split("\n")
-            .map((line) => /^export \* as (\S+) from/.exec(line)?.[1])
+            .map(
+              (line) =>
+                /^export \* as \S+ from "\.\/(.+)\.ts";/.exec(line)?.[1],
+            )
             .filter((name): name is string => name !== undefined);
           // Ordered exactly as a full run orders it: by MODEL FILENAME, so
           // the `.json` takes part in the collation (`ai_gateway.json` sorts
@@ -243,11 +321,14 @@ export const runGeneratorCli = (options: GeneratorCliOptions): void => {
           barrelPath,
           barrel(
             `// AUTO-GENERATED by scripts/generate.ts. Do not edit.\n`,
-            resources.map((r) => ({ name: r, path: `./${r}.ts` })),
+            resources.map((r) => ({
+              name: options.barrelExportName?.(r) ?? r,
+              path: `./${r}.ts`,
+            })),
           ),
         );
 
-        yield* formatGenerated(outDir);
+        yield* (options.finalize ?? formatGenerated)(outDir);
 
         yield* Console.log(
           `\n✅ Generated ${totalOps} operations across ${written.length} resource modules` +
@@ -256,6 +337,19 @@ export const runGeneratorCli = (options: GeneratorCliOptions): void => {
               : "."),
         );
         yield* Console.log(`   ${path.join(outDir, "index.ts")}`);
+
+        // Models that failed under continueOnModelError. Reported together,
+        // at the end, and the run FAILS — a generate that couldn't produce
+        // a module must not exit 0 with the failure buried in the log.
+        if (failedModels.length) {
+          yield* Console.error(
+            `\n❌ ${failedModels.length} model(s) failed to generate:`,
+          );
+          for (const f of failedModels) yield* Console.error(`   ${f}`);
+          return yield* Effect.die(
+            new Error(`${failedModels.length} model(s) failed to generate`),
+          );
+        }
       }),
   ).pipe(Command.withDescription(options.description));
 

package/src/codegen/emit.ts

@@ -9,7 +9,7 @@
  *     .annotate({ identifier: "X" })
  *     as any as S.Schema<X>;                      // no inference needed
  *
- * plus closed-alias string-union enums, `S.TaggedErrorClass` error classes, and
+ * plus closed-alias string-union enums, `S.TaggedError` 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,
@@ -120,7 +120,7 @@ export interface ErrorClassOptions {
 }
 
 /**
- * `export class X extends /*@__PURE__*​/ S.TaggedErrorClass<X>()("X", { … }) {}`
+ * `export class X extends /*@__PURE__*​/ S.TaggedError<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 —
@@ -130,12 +130,12 @@ export interface ErrorClassOptions {
  *
  * `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
+ * `T.applyErrorMatchers(S.TaggedError…(…), […])` leaves the inner call
  * holding the class alive. Verified against esbuild in both directions.
  */
 export const errorClass = (o: ErrorClassOptions): string => {
   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 cls = `${PURE}S.TaggedError<${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`;
 };

package/src/codegen/generator.ts

@@ -487,8 +487,27 @@ export const generateService = (
   const order = topoOrder(shapes, reachable, shapeDeps);
   const indexOf = orderIndex(order);
 
-  const ref = makeSchemaRef(prelude, indexOf);
-  const tsRef = makeTsRef(tsPrelude);
+  /**
+   * Shape id → the id whose emitted body it shares.
+   *
+   * Structural aliasing (see the struct emission below) has to cascade: a
+   * parent only matches another parent if their MEMBERS render identically,
+   * and a member renders as its target's name. So every reference resolves
+   * through this map first — once `…ItemGroupRuleGroup` is aliased onto a
+   * canonical shape, the parents referencing it start rendering the same
+   * text and collapse in turn.
+   *
+   * Filled in topological order, so a canonical target is always a shape
+   * that was already emitted — a back-reference, never a forward one.
+   */
+  const canonicalId = new Map<string, string>();
+  const canon = (target: string): string => canonicalId.get(target) ?? target;
+
+  const rawRef = makeSchemaRef(prelude, indexOf);
+  const rawTsRef = makeTsRef(tsPrelude);
+  const ref = (target: string, selfIdx: number) =>
+    rawRef(canon(target), selfIdx);
+  const tsRef = (target: string) => rawTsRef(canon(target));
 
   // Direction classification for enum openness. Enum ALIASES are emitted
   // CLOSED (exhaustively matchable on reads); request-reachable shapes
@@ -529,7 +548,8 @@ export const generateService = (
    * pure response/error shapes stay the plain closed alias, and so do
    * union-arm discriminant literals.
    */
-  const tsRefAt = (target: string, ownerId: string): string => {
+  const tsRefAt = (rawTarget: string, ownerId: string): string => {
+    const target = canon(rawTarget);
     const base = tsRef(target);
     if (!requestReachable.has(ownerId)) return base;
     if (discriminantEnums.has(target)) return base;
@@ -731,6 +751,13 @@ export const generateService = (
 
   // 4. Error classes from the operations' errors lists.
   const out: string[] = [];
+  // Emitted struct body → the name that owns it, for structural aliasing.
+  // Keyed on the emitted TEXT, so two shapes collapse only when what they
+  // would emit is byte-identical — including member names, targets, docs and
+  // pipes. References are already resolved to names at this point, so a
+  // difference anywhere in the tree shows up as different text.
+  const structBodies = new Map<string, { id: string; name: string }>();
+  let aliased = 0;
   // Set when any error carries CATEGORY_TRAIT, so the header only imports
   // the category module when something actually uses it.
   let usesCategories = false;
@@ -866,7 +893,6 @@ export const generateService = (
         fields.push(...inject.interfaceLines);
         members.push(inject.structLine);
       }
-      out.push(interfaceDecl(name, fields));
       const struct = members.length
         ? `S.Struct({\n${members.join("\n")}\n})`
         : `S.Struct({})`;
@@ -884,15 +910,44 @@ export const generateService = (
           : []),
       ];
       const tail = pipes.map((p) => `.pipe(${p})`).join("");
-      out.push(
-        suspendConst({
-          name,
-          pure,
-          multiline: true,
-          annotateIdentifier: true,
-          expr: `${struct}${tail}`,
-        }),
-      );
+
+      // Shapes whose emitted body is byte-identical are one shape wearing
+      // many names. The docs pipelines generate a fresh copy of every nested
+      // shape per operation, so cloudflare's zero_trust carries 374 copies of
+      // `{ group?: unknown }` — one per operation x application type x
+      // include/exclude/require — and 72% of its 16,800 structures are
+      // redundant that way.
+      //
+      // Emit the body once and alias the rest to it. The public name is kept,
+      // so nothing about the surface changes; only the duplicate bodies go.
+      // Operation I/O is excluded: those carry the operation's Http trait and
+      // must never be merged onto one another.
+      const bodyKey = `${JSON.stringify(fields)}|${struct}${tail}`;
+      const canonical = structCtx.isOpIo
+        ? undefined
+        : structBodies.get(bodyKey);
+      if (canonical !== undefined) {
+        out.push(`export type ${name} = ${canonical.name};`);
+        out.push(`export const ${name} = ${canonical.name};\n`);
+        // Later shapes referencing this one now render the canonical name,
+        // which is what lets their bodies collapse too.
+        canonicalId.set(id, canonical.id);
+        aliased++;
+      } else {
+        if (!structCtx.isOpIo) {
+          structBodies.set(bodyKey, { id, name });
+        }
+        out.push(interfaceDecl(name, fields));
+        out.push(
+          suspendConst({
+            name,
+            pure,
+            multiline: true,
+            annotateIdentifier: true,
+            expr: `${struct}${tail}`,
+          }),
+        );
+      }
     } else if (d.type === "list") {
       out.push(`export type ${name} = Array<${tsRefAt(d.member.target, id)}>;`);
       out.push(
@@ -975,14 +1030,26 @@ export const generateService = (
     // No items path: `.items()` is a page passthrough at runtime, so an
     // item IS a whole response.
     if (!itemsPath) return tsRef(outputId);
-    let def = shapes[outputId];
+    let id: string = outputId;
+    // Whether the path crossed a list on the way down (`"edges.node"` on a
+    // Relay connection). When it did, the path itself is what fans out, so
+    // the value it lands on IS one item — it needn't be a list again.
+    let fannedOut = false;
     for (const segment of itemsPath.split(".")) {
+      let def: any = shapes[id];
+      if (def?.type === "list") {
+        id = def.member.target as string;
+        def = shapes[id];
+        fannedOut = true;
+      }
       if (def?.type !== "structure") return undefined;
       const info = memberInfos(def).find((m) => m.tsName === segment);
       if (!info) return undefined;
-      def = shapes[info.target];
+      id = info.target;
     }
-    return def?.type === "list" ? tsRef(def.member.target) : undefined;
+    const last: any = shapes[id];
+    if (last?.type === "list") return tsRef(last.member.target);
+    return fannedOut ? tsRef(id) : undefined;
   };
 
   const emitOperation =