@distilled.cloud/core 0.30.2 → 1.0.0-rc.1

package/src/codegen/operations.ts

@@ -0,0 +1,76 @@
+/**
+ * Operation-level smithy helpers for the SDK generators (dev-time only).
+ */
+import { local } from "./naming.ts";
+import type { ShapeMap } from "./graph.ts";
+
+export interface OpEntry {
+  id: string;
+  def: any;
+}
+
+/** All operation shapes, sorted by local name. */
+export const collectOperations = (shapes: ShapeMap): OpEntry[] => {
+  const operations: OpEntry[] = [];
+  for (const [id, def] of Object.entries(shapes)) {
+    if (def.type === "operation") operations.push({ id, def });
+  }
+  operations.sort((a, b) => local(a.id).localeCompare(local(b.id)));
+  return operations;
+};
+
+/** The model's shape namespace (from the first operation, else any shape). */
+export const modelNamespace = (
+  operations: readonly OpEntry[],
+  shapes: ShapeMap,
+  fallback: string,
+): string =>
+  operations.length
+    ? operations[0].id.split("#")[0]
+    : (Object.keys(shapes)[0]?.split("#")[0] ?? fallback);
+
+/**
+ * Resolve an operation's input/output targets, synthesizing an empty named
+ * structure for `smithy.api#Unit` so every operation has a shape that can
+ * carry operation-level traits (mutates `shapes`).
+ */
+export const ensureNamedIo = (
+  shapes: ShapeMap,
+  op: OpEntry,
+  ns: string,
+): { input: string; output: string } => {
+  const opName = local(op.id);
+  let input = op.def.input?.target ?? "smithy.api#Unit";
+  let output = op.def.output?.target ?? "smithy.api#Unit";
+  if (input === "smithy.api#Unit") {
+    input = `${ns}#${opName}Request`;
+    shapes[input] = { type: "structure", members: {} };
+  }
+  if (output === "smithy.api#Unit") {
+    output = `${ns}#${opName}Response`;
+    shapes[output] = { type: "structure", members: {} };
+  }
+  return { input, output };
+};
+
+/**
+ * Every error shape id referenced by the operations' `errors` lists —
+ * deduplicated, existing in the model, sorted by local name.
+ */
+export const collectOpErrorIds = (
+  operations: readonly OpEntry[],
+  shapes: ShapeMap,
+): string[] => {
+  const errorIds: string[] = [];
+  const seen = new Set<string>();
+  for (const op of operations) {
+    for (const e of op.def.errors ?? []) {
+      if (!seen.has(e.target) && shapes[e.target]) {
+        seen.add(e.target);
+        errorIds.push(e.target);
+      }
+    }
+  }
+  errorIds.sort((a, b) => local(a).localeCompare(local(b)));
+  return errorIds;
+};

package/src/codegen/pagination.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared pagination-trait handling for the SDK generators (dev-time only).
+ *
+ * Both SDKs source `smithy.api#paginated`; AWS merges operation-level
+ * config over service-level defaults, cloudflare validates the trait
+ * against the operation's actual members (degrading to a plain op when it
+ * can't work). Both behaviors live here.
+ */
+import type { PaginatedTrait } from "../pagination.ts";
+
+/**
+ * Merge an operation-level paginated trait over service-level defaults
+ * (Smithy semantics: operations may specify partial pagination and inherit
+ * the rest from the service).
+ */
+export const mergePaginated = (
+  op: Partial<PaginatedTrait> | undefined,
+  service: Partial<PaginatedTrait> | undefined,
+): PaginatedTrait | undefined => {
+  if (!op) return undefined;
+  const merged = {
+    mode: op.mode ?? service?.mode,
+    inputToken: op.inputToken ?? service?.inputToken,
+    outputToken: op.outputToken ?? service?.outputToken,
+    items: op.items ?? service?.items,
+    pageSize: op.pageSize ?? service?.pageSize,
+  };
+  return Object.fromEntries(
+    Object.entries(merged).filter(([, v]) => v !== undefined),
+  ) as PaginatedTrait;
+};
+
+export interface ValidatePaginatedOptions {
+  readonly trait: Partial<PaginatedTrait>;
+  /** TS-facing member names of the operation input shape. */
+  readonly inputNames: ReadonlySet<string>;
+  /** TS-facing member names of the operation output shape. */
+  readonly outputNames: ReadonlySet<string>;
+  /** Items path fallback when the trait omits `items` (e.g. `"result"`). */
+  readonly itemsFallback?: string;
+  /** Output names accepted even when not modeled (e.g. `"resultInfo"`). */
+  readonly syntheticOutputs?: ReadonlySet<string>;
+}
+
+export interface ValidatedPagination {
+  readonly ok: boolean;
+  /** Root member of the items path (`"result.items"` → `"result"`). */
+  readonly itemsRoot: string;
+}
+
+/**
+ * A paginated op must actually carry its page/cursor token on the input
+ * and its items member on the output — otherwise `.pages()` would loop or
+ * yield nothing. Returns the items-path root for emitters that promote it
+ * to required.
+ */
+export const validatePaginated = (
+  o: ValidatePaginatedOptions,
+): ValidatedPagination => {
+  const itemsRoot = String(o.trait.items ?? o.itemsFallback ?? "").split(
+    ".",
+  )[0];
+  const tokenOk =
+    o.trait.mode === "single" ||
+    (typeof o.trait.inputToken === "string" &&
+      o.inputNames.has(o.trait.inputToken));
+  const itemsOk =
+    o.outputNames.has(itemsRoot) ||
+    (o.syntheticOutputs?.has(itemsRoot) ?? false);
+  return { ok: tokenOk && itemsOk, itemsRoot };
+};

package/src/codegen/prelude.ts

@@ -0,0 +1,70 @@
+/**
+ * Smithy prelude scalar baselines + reference resolvers for the SDK
+ * generators (dev-time only).
+ *
+ * The JSON flavor maps timestamps/blobs to plain strings — the baseline for
+ * SDKs whose wire format is JSON-over-docs (cloudflare). Generators with
+ * richer models (AWS) emit real timestamp/blob schemas themselves and only
+ * fall back here for untyped scalars.
+ */
+import { isPrelude, local } from "./naming.ts";
+import { isForwardRef } from "./graph.ts";
+
+/** Prelude shape → schema expression (JSON-wire flavor). */
+export const JSON_PRELUDE: Record<string, string> = {
+  String: "S.String",
+  Boolean: "S.Boolean",
+  Double: "S.Number",
+  Float: "S.Number",
+  Integer: "S.Number",
+  Long: "S.Number",
+  BigInteger: "S.Number",
+  BigDecimal: "S.Number",
+  Timestamp: "S.String",
+  Blob: "S.String",
+  Document: "S.Unknown",
+  Unit: "S.Struct({})",
+};
+
+/** TypeScript type for each prelude shape, mirroring {@link JSON_PRELUDE}. */
+export const TS_JSON_PRELUDE: Record<string, string> = {
+  String: "string",
+  Boolean: "boolean",
+  Double: "number",
+  Float: "number",
+  Integer: "number",
+  Long: "number",
+  BigInteger: "number",
+  BigDecimal: "number",
+  Timestamp: "string",
+  Blob: "string",
+  Document: "unknown",
+  Unit: "{}",
+};
+
+/**
+ * Schema reference resolver: prelude shapes map through the prelude table,
+ * forward references (including into cycles) wrap in `S.suspend`.
+ */
+export const makeSchemaRef =
+  (
+    prelude: Record<string, string>,
+    indexOf: ReadonlyMap<string, number>,
+  ): ((target: string, selfIdx: number) => string) =>
+  (target, selfIdx) => {
+    if (isPrelude(target)) return prelude[local(target)] ?? "S.Unknown";
+    const name = local(target);
+    if (isForwardRef(indexOf, target, selfIdx)) {
+      return `S.suspend(() => ${name})`;
+    }
+    return name;
+  };
+
+/**
+ * TypeScript type reference resolver. Named shapes all get an emitted
+ * interface / type alias, so forward references are always fine.
+ */
+export const makeTsRef =
+  (tsPrelude: Record<string, string>): ((target: string) => string) =>
+  (target) =>
+    isPrelude(target) ? (tsPrelude[local(target)] ?? "unknown") : local(target);

package/src/error-category.ts

@@ -0,0 +1,84 @@
+import { Effect, Predicate } from "effect";
+
+export const categoriesKey = "@distilled/meta/error-categories";
+
+export const withCategory =
+  <Categories extends Array<PropertyKey>>(...categories: Categories) =>
+  <Args extends Array<any>, Ret, C extends { new (...args: Args): Ret }>(
+    C: C,
+  ): C & {
+    new (...args: Args): Ret & {
+      [categoriesKey]: { [Cat in Categories[number]]: true };
+    };
+  } => {
+    // @ts-expect-error
+    const Mixed = class extends C {};
+
+    for (const category of categories) {
+      if (!(categoriesKey in Mixed.prototype)) {
+        // @ts-expect-error
+        Mixed.prototype[categoriesKey] = {};
+      }
+      // @ts-expect-error
+      Mixed.prototype[categoriesKey][category] = true;
+    }
+
+    return Mixed as any;
+  };
+
+export type AllKeys<E> = E extends { [categoriesKey]: infer Q }
+  ? keyof Q
+  : never;
+
+export type ExtractAll<E, Cats extends PropertyKey> = Cats extends any
+  ? Extract<E, { [categoriesKey]: { [K in Cats]: any } }>
+  : never;
+
+/**
+ * Runtime check: does `value` carry the given category?
+ * Works on instances tagged via `withCategory(...)`.
+ */
+export const hasCategory =
+  <const Cat extends PropertyKey>(category: Cat) =>
+  (
+    value: unknown,
+  ): value is { readonly [categoriesKey]: { readonly [K in Cat]: true } } => {
+    if (!Predicate.isObject(value)) return false;
+    if (!Predicate.hasProperty(categoriesKey)(value)) return false;
+    return category in (value as any)[categoriesKey];
+  };
+
+/** True if `value` has any of the given categories. */
+export const hasAnyCategory =
+  (...categories: ReadonlyArray<PropertyKey>) =>
+  (value: unknown): boolean => {
+    if (!Predicate.isObject(value)) return false;
+    if (!Predicate.hasProperty(categoriesKey)(value)) return false;
+    const cats = (value as any)[categoriesKey];
+    for (const c of categories) if (c in cats) return true;
+    return false;
+  };
+
+export const catchCategory =
+  <E, const Categories extends Array<AllKeys<E>>, A2, E2, R2>(
+    ...args: [
+      ...Categories,
+      f: (err: ExtractAll<E, Categories[number]>) => Effect.Effect<A2, E2, R2>,
+    ]
+  ) =>
+  <A, R>(
+    effect: Effect.Effect<A, E, R>,
+  ): Effect.Effect<
+    A | A2,
+    E2 | Exclude<E, ExtractAll<E, Categories[number]>>,
+    R | R2
+  > => {
+    const f = args.pop()! as (
+      err: ExtractAll<E, Categories[number]>,
+    ) => Effect.Effect<A2, E2, R2>;
+    const categories = args as Array<PropertyKey>;
+    const matches = hasAnyCategory(...categories);
+    return Effect.catchIf(effect, matches, (e) =>
+      f(e as ExtractAll<E, Categories[number]>),
+    ) as any;
+  };

package/src/errors.ts

@@ -228,3 +228,5 @@ export const DEFAULT_ERRORS = [
 ] as const;
 
 export type DefaultErrors = InstanceType<(typeof DEFAULT_ERRORS)[number]>;
+
+export const RETRYABLE = "@distilled/errors/retryable" as const;

package/src/json-patch.ts

@@ -1,20 +1,14 @@
 /**
  * JSON Patch (RFC 6902) Implementation
  *
- * Provides a unified spec patching system for all SDKs.
- * Patches are applied to OpenAPI/Discovery/Smithy specs before code generation
- * to add error types, fix nullable fields, mark sensitive data, etc.
+ * Provides a unified spec patching system for all SDKs. Patches are applied to
+ * generated intermediary specs (Smithy models, OpenAPI docs, …) before code
+ * generation to add typed error shapes, rename operations, mark nullable
+ * fields, etc. Ported from the distilled repo's `core/json-patch`.
  *
- * @example
- * ```ts
- * import { applyAllPatches } from "@distilled.cloud/core/json-patch";
- *
- * const spec = JSON.parse(fs.readFileSync("openapi.json", "utf-8"));
- * const { applied, errors } = applyAllPatches(spec, "./patches");
- * ```
+ * Pure functions only — callers load patch files themselves (the generators
+ * use Effect's FileSystem) and hand the parsed operations to `applyPatch`.
  */
-import * as fs from "fs";
-import * as path from "path";
 
 // ============================================================================
 // Types
@@ -30,7 +24,7 @@ export interface JsonPatchOperation {
 export type JsonPatch = JsonPatchOperation[];
 
 export interface PatchFile {
-  description: string;
+  description?: string;
   patches: JsonPatch;
 }
 
@@ -38,9 +32,7 @@ export interface PatchFile {
 // JSON Pointer (RFC 6901)
 // ============================================================================
 
-/**
- * Parse a JSON Pointer (RFC 6901) path into segments.
- */
+/** Parse a JSON Pointer (RFC 6901) path into segments. */
 export function parseJsonPointer(pointer: string): string[] {
   if (pointer === "") return [];
   if (!pointer.startsWith("/")) {
@@ -52,9 +44,7 @@ export function parseJsonPointer(pointer: string): string[] {
     .map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
 }
 
-/**
- * Get a value at a JSON Pointer path.
- */
+/** Get a value at a JSON Pointer path. */
 export function getValueAtPath(obj: unknown, pointer: string): unknown {
   const segments = parseJsonPointer(pointer);
   let current: unknown = obj;
@@ -74,9 +64,7 @@ export function getValueAtPath(obj: unknown, pointer: string): unknown {
   return current;
 }
 
-/**
- * Set a value at a JSON Pointer path.
- */
+/** Set a value at a JSON Pointer path. */
 export function setValueAtPath(
   obj: unknown,
   pointer: string,
@@ -95,8 +83,7 @@ export function setValueAtPath(
       throw new Error(`Cannot traverse path ${pointer}: not an object`);
     }
     if (Array.isArray(current)) {
-      const index = parseInt(segment, 10);
-      current = current[index];
+      current = current[parseInt(segment, 10)];
     } else {
       current = (current as Record<string, unknown>)[segment];
     }
@@ -110,21 +97,17 @@ export function setValueAtPath(
   }
 
   if (Array.isArray(current)) {
-    const index =
-      lastSegment === "-" ? current.length : parseInt(lastSegment, 10);
     if (lastSegment === "-") {
       current.push(value);
     } else {
-      current[index] = value;
+      current[parseInt(lastSegment, 10)] = value;
     }
   } else {
     (current as Record<string, unknown>)[lastSegment] = value;
   }
 }
 
-/**
- * Remove a value at a JSON Pointer path.
- */
+/** Remove a value at a JSON Pointer path. */
 export function removeValueAtPath(obj: unknown, pointer: string): void {
   const segments = parseJsonPointer(pointer);
   if (segments.length === 0) {
@@ -163,9 +146,7 @@ export function removeValueAtPath(obj: unknown, pointer: string): void {
 // Patch Operations
 // ============================================================================
 
-/**
- * Apply a single JSON Patch operation.
- */
+/** Apply a single JSON Patch operation (mutates `obj` in place). */
 export function applyOperation(
   obj: unknown,
   operation: JsonPatchOperation,
@@ -185,6 +166,11 @@ export function applyOperation(
     case "move": {
       if (!operation.from) throw new Error("move operation requires 'from'");
       const moveValue = getValueAtPath(obj, operation.from);
+      if (moveValue === undefined) {
+        throw new Error(
+          `Cannot move from path ${operation.from}: not an object`,
+        );
+      }
       removeValueAtPath(obj, operation.from);
       setValueAtPath(obj, operation.path, moveValue);
       break;
@@ -213,9 +199,7 @@ export function applyOperation(
   }
 }
 
-/**
- * Apply a JSON Patch to an object (mutates in place).
- */
+/** Apply a JSON Patch to an object (mutates in place). */
 export function applyPatch(obj: unknown, patch: JsonPatch): void {
   for (const operation of patch) {
     applyOperation(obj, operation);
@@ -224,83 +208,15 @@ export function applyPatch(obj: unknown, patch: JsonPatch): void {
 
 /**
  * Whether a per-operation failure is caused by the target location being
- * absent from the spec (i.e. vendor spec drift — the operation/schema the
- * patch targets was renamed or removed upstream) as opposed to a malformed
- * patch. Stale targets are skipped with a warning rather than aborting the
- * whole generate; a patch that only adds an error response to an operation
- * that no longer exists is harmless to drop.
+ * absent from the spec (i.e. spec drift — the operation/shape the patch
+ * targets was renamed or removed upstream) as opposed to a malformed patch.
+ * Stale targets should be skipped with a warning rather than aborting the
+ * whole generate; a patch that only adds an error to an operation that no
+ * longer exists is harmless to drop.
  */
-function isStaleTargetError(message: string): boolean {
+export function isStaleTargetError(message: string): boolean {
   return (
     message.includes("not an object") ||
     message.includes("parent is not an object")
   );
 }
-
-/**
- * Load and apply all patches from a directory.
- * Finds all *.patch.json files and applies them.
- *
- * Each operation within a patch file is applied independently. Operations
- * whose target path no longer exists in the spec (vendor spec drift) are
- * collected as `skipped` warnings and do not abort generation. Only genuine
- * failures (malformed JSON, invalid pointers, failed `test` ops) are reported
- * as `errors`.
- */
-export function applyAllPatches(
-  spec: unknown,
-  patchDir: string,
-): { applied: string[]; skipped: string[]; errors: string[] } {
-  const applied: string[] = [];
-  const skipped: string[] = [];
-  const errors: string[] = [];
-
-  if (!fs.existsSync(patchDir)) {
-    return { applied, skipped, errors };
-  }
-
-  // Find all .patch.json files
-  const files = fs
-    .readdirSync(patchDir)
-    .filter((f) => f.endsWith(".patch.json"))
-    .sort(); // Sort for deterministic application order
-
-  for (const file of files) {
-    const filePath = path.join(patchDir, file);
-    let patchFile: PatchFile;
-    try {
-      const content = fs.readFileSync(filePath, "utf-8");
-      patchFile = JSON.parse(content);
-    } catch (error) {
-      errors.push(
-        `${file}: ${error instanceof Error ? error.message : String(error)}`,
-      );
-      continue;
-    }
-
-    let appliedAny = false;
-    for (const operation of patchFile.patches) {
-      try {
-        applyOperation(spec, operation);
-        appliedAny = true;
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        if (isStaleTargetError(message)) {
-          skipped.push(
-            `${file} [${operation.op} ${operation.path}]: ${message}`,
-          );
-        } else {
-          errors.push(
-            `${file} [${operation.op} ${operation.path}]: ${message}`,
-          );
-        }
-      }
-    }
-
-    if (appliedAny) {
-      applied.push(`${file}: ${patchFile.description}`);
-    }
-  }
-
-  return { applied, skipped, errors };
-}