@outfitter/contracts 0.4.2 → 0.5.0

package/dist/schema.js

@@ -1,29 +1,21 @@
 // @bun
+import {
+  convertNumber,
+  convertString
+} from "./shared/@outfitter/contracts-3re9d4bp.js";
+import {
+  convertArray,
+  convertObject
+} from "./shared/@outfitter/contracts-hrepwwne.js";
+import {
+  getDef,
+  getDescription
+} from "./shared/@outfitter/contracts-jyhqr766.js";
+
 // packages/contracts/src/schema.ts
 function zodToJsonSchema(schema) {
   return convertZodType(schema);
 }
-function getDef(schemaOrDef) {
-  if (!schemaOrDef) {
-    return;
-  }
-  if (schemaOrDef._def) {
-    return schemaOrDef._def;
-  }
-  if (schemaOrDef.def) {
-    return schemaOrDef.def;
-  }
-  return schemaOrDef;
-}
-function getDescription(schema, def) {
-  if (typeof schema?.description === "string") {
-    return schema.description;
-  }
-  if (typeof def?.description === "string") {
-    return def.description;
-  }
-  return;
-}
 function convertZodType(schema) {
   const def = getDef(schema);
   if (!def) {
@@ -54,11 +46,11 @@ function convertZodType(schema) {
       break;
     case "ZodArray":
     case "array":
-      jsonSchema = convertArray(def);
+      jsonSchema = convertArray(def, convertZodType);
       break;
     case "ZodObject":
     case "object":
-      jsonSchema = convertObject(def);
+      jsonSchema = convertObject(def, convertZodType);
       break;
     case "ZodOptional":
     case "optional":
@@ -173,170 +165,6 @@ function convertZodType(schema) {
   }
   return jsonSchema;
 }
-function convertString(def) {
-  const schema = { type: "string" };
-  if (def.checks) {
-    for (const check of def.checks) {
-      const normalizedCheck = check?._zod?.def ?? check?.def ?? check;
-      if (normalizedCheck?.kind) {
-        switch (normalizedCheck.kind) {
-          case "min":
-            schema.minLength = normalizedCheck.value;
-            break;
-          case "max":
-            schema.maxLength = normalizedCheck.value;
-            break;
-          case "length":
-            schema.minLength = normalizedCheck.value;
-            schema.maxLength = normalizedCheck.value;
-            break;
-          case "email":
-            schema.pattern = "^[^@]+@[^@]+\\.[^@]+$";
-            break;
-          case "url":
-            schema.pattern = "^https?://";
-            break;
-          case "uuid":
-            schema.pattern = "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$";
-            break;
-          case "regex":
-            schema.pattern = normalizedCheck.regex?.source ?? normalizedCheck.pattern?.source ?? (typeof normalizedCheck.pattern === "string" ? normalizedCheck.pattern : undefined);
-            break;
-          default:
-            break;
-        }
-        continue;
-      }
-      if (!normalizedCheck?.check) {
-        continue;
-      }
-      switch (normalizedCheck.check) {
-        case "min_length":
-          schema.minLength = normalizedCheck.minimum;
-          break;
-        case "max_length":
-          schema.maxLength = normalizedCheck.maximum;
-          break;
-        case "string_format":
-          if (normalizedCheck.pattern) {
-            schema.pattern = typeof normalizedCheck.pattern === "string" ? normalizedCheck.pattern : normalizedCheck.pattern.source;
-          }
-          if (normalizedCheck.format && normalizedCheck.format !== "regex") {
-            schema.format = normalizedCheck.format;
-          }
-          break;
-        default:
-          break;
-      }
-    }
-  }
-  return schema;
-}
-function convertNumber(def) {
-  const schema = { type: "number" };
-  if (def.checks) {
-    for (const check of def.checks) {
-      const normalizedCheck = check?._zod?.def ?? check?.def ?? check;
-      if (normalizedCheck?.kind) {
-        switch (normalizedCheck.kind) {
-          case "min":
-            schema.minimum = normalizedCheck.value;
-            break;
-          case "max":
-            schema.maximum = normalizedCheck.value;
-            break;
-          case "int":
-            schema.type = "integer";
-            break;
-          default:
-            break;
-        }
-        continue;
-      }
-      if (!normalizedCheck?.check) {
-        continue;
-      }
-      switch (normalizedCheck.check) {
-        case "greater_than":
-          if (normalizedCheck.inclusive) {
-            schema.minimum = normalizedCheck.value;
-          } else {
-            schema.exclusiveMinimum = normalizedCheck.value;
-          }
-          break;
-        case "less_than":
-          if (normalizedCheck.inclusive) {
-            schema.maximum = normalizedCheck.value;
-          } else {
-            schema.exclusiveMaximum = normalizedCheck.value;
-          }
-          break;
-        case "number_format":
-          if (normalizedCheck.format === "int" || normalizedCheck.format === "safeint") {
-            schema.type = "integer";
-          }
-          break;
-        default:
-          break;
-      }
-    }
-  }
-  return schema;
-}
-function convertArray(def) {
-  const element = def.element ?? def.type;
-  const schema = {
-    type: "array",
-    items: element ? convertZodType(element) : {}
-  };
-  return schema;
-}
-function isFieldOptional(fieldDef) {
-  if (!(fieldDef?.typeName || fieldDef?.type)) {
-    return false;
-  }
-  const typeName = fieldDef.typeName ?? fieldDef.type;
-  if (typeName === "ZodOptional" || typeName === "ZodDefault" || typeName === "optional" || typeName === "default") {
-    return true;
-  }
-  if (typeName === "ZodEffects") {
-    return isFieldOptional(getDef(fieldDef.schema));
-  }
-  if (typeName === "ZodPipeline" || typeName === "pipe") {
-    const inputOptional = isFieldOptional(getDef(fieldDef.in));
-    const outputDef = getDef(fieldDef.out);
-    const outputType = outputDef?.typeName ?? outputDef?.type;
-    if (outputType === "transform") {
-      return inputOptional;
-    }
-    const outputOptional = isFieldOptional(outputDef);
-    return inputOptional && outputOptional;
-  }
-  if (typeName === "ZodNullable" || typeName === "nullable") {
-    return isFieldOptional(getDef(fieldDef.innerType));
-  }
-  return false;
-}
-function convertObject(def) {
-  const properties = {};
-  const required = [];
-  const shape = typeof def.shape === "function" ? def.shape() : def.shape;
-  for (const [key, value] of Object.entries(shape ?? {})) {
-    properties[key] = convertZodType(value);
-    const fieldDef = getDef(value);
-    if (!isFieldOptional(fieldDef)) {
-      required.push(key);
-    }
-  }
-  const schema = {
-    type: "object",
-    properties
-  };
-  if (required.length > 0) {
-    schema.required = required;
-  }
-  return schema;
-}
 export {
   zodToJsonSchema
 };

package/dist/serialization.d.ts

@@ -1,3 +1,9 @@
-import { SerializeErrorOptions, deserializeError, safeParse, safeStringify, serializeError } from "./shared/@outfitter/contracts-31penhwa.js";
-import "./shared/@outfitter/contracts-3gswmhb1.js";
+import "./shared/@outfitter/contracts-f6fnz6h9.js";
+import { SerializeErrorOptions, deserializeError, serializeError } from "./shared/@outfitter/contracts-p77yjs4g.js";
+import { safeParse, safeStringify } from "./shared/@outfitter/contracts-1zzcpfyg.js";
+import "./shared/@outfitter/contracts-7a0xmwbg.js";
+import "./shared/@outfitter/contracts-735ecmbq.js";
+import "./shared/@outfitter/contracts-mehpmvwp.js";
+import "./shared/@outfitter/contracts-qpbv29bg.js";
+import "./shared/@outfitter/contracts-njb2art4.js";
 export { serializeError, safeStringify, safeParse, deserializeError, SerializeErrorOptions };

package/dist/serialization.js

@@ -4,9 +4,7 @@ import {
   safeParse,
   safeStringify,
   serializeError
-} from "./shared/@outfitter/contracts-5k6q4n48.js";
-import"./shared/@outfitter/contracts-phjhz5q3.js";
-import"./shared/@outfitter/contracts-s15x2rs4.js";
+} from "./shared/@outfitter/contracts-jtt6dnmg.js";
 export {
   serializeError,
   safeStringify,

package/dist/shared/@outfitter/{contracts-k71jqd1m.d.ts → contracts-10p5q75w.d.ts}

@@ -1,4 +1,4 @@
-import { ErrorCategory } from "./contracts-3gswmhb1.js";
+import { ErrorCategory } from "./contracts-njb2art4.js";
 /**
 * Backoff strategy configuration options
 */

package/dist/shared/@outfitter/contracts-1zzcpfyg.d.ts

@@ -0,0 +1,40 @@
+import { ValidationError } from "./contracts-mehpmvwp.js";
+import { Result } from "better-result";
+import { z } from "zod";
+/**
+* Safely stringify any value to JSON.
+*
+* Handles circular references, BigInt, and other non-JSON-safe values.
+* Applies redaction to sensitive values.
+*
+* @param value - Value to stringify
+* @param space - Indentation (default: undefined for compact)
+* @returns JSON string
+*
+* @example
+* ```typescript
+* const json = safeStringify({ apiKey: "sk-secret", data: "safe" });
+* // '{"apiKey":"[REDACTED]","data":"safe"}'
+* ```
+*/
+declare function safeStringify(value: unknown, space?: number): string;
+/**
+* Safely parse JSON string with optional schema validation.
+*
+* Returns Result instead of throwing on invalid JSON.
+*
+* @typeParam T - Expected parsed type (or unknown if no schema)
+* @param json - JSON string to parse
+* @param schema - Optional Zod schema for validation
+* @returns Result with parsed value or ValidationError
+*
+* @example
+* ```typescript
+* const result = safeParse<Config>('{"port": 3000}', ConfigSchema);
+* if (result.isOk()) {
+*   const config = result.unwrap();
+* }
+* ```
+*/
+declare function safeParse<T = unknown>(json: string, schema?: z.ZodType<T>): Result<T, ValidationError>;
+export { safeStringify, safeParse };

package/dist/shared/@outfitter/contracts-3f5k5tg5.d.ts

@@ -0,0 +1,28 @@
+import { OutfitterError } from "./contracts-7a0xmwbg.js";
+import { Result } from "better-result";
+/**
+* Convert an HTTP {@link Response} into a `Result<Response, OutfitterError>`.
+*
+* - **2xx** status codes return `Ok` with the original Response.
+* - Known error codes map to specific categories per the taxonomy using
+*   {@link statusCodeMap} plus {@link HTTP_STATUS_ALIASES} for 408 and 503.
+* - Unmapped 4xx → validation, unmapped 5xx → internal.
+* - All other codes (1xx, 3xx) → internal.
+*
+* @param response - The HTTP Response to inspect
+* @returns `Result.ok(response)` for 2xx, `Result.err(OutfitterError)` otherwise
+*
+* @example
+* ```typescript
+* const response = await fetch("https://api.example.com/data");
+* const result = fromFetch(response);
+*
+* if (result.isOk()) {
+*   const data = await result.value.json();
+* } else {
+*   console.error(result.error.category, result.error.message);
+* }
+* ```
+*/
+declare function fromFetch(response: Response): Result<Response, OutfitterError>;
+export { fromFetch };

package/dist/shared/@outfitter/contracts-3qmyq81n.d.ts

@@ -0,0 +1,78 @@
+import { AssertionError } from "./contracts-mehpmvwp.js";
+import { Result } from "better-result";
+/**
+* Array type guaranteed to have at least one element.
+*/
+type NonEmptyArray<T> = [T, ...T[]];
+/**
+* Type guard for NonEmptyArray.
+*/
+declare const isNonEmptyArray: <T>(arr: readonly T[]) => arr is NonEmptyArray<T>;
+/**
+* Assert a value is defined (not null or undefined).
+* Returns Result instead of throwing.
+*/
+declare const assertDefined: <T>(value: T | null | undefined, message?: string) => Result<T, InstanceType<typeof AssertionError>>;
+/**
+* Assert array has at least one element.
+* Returns NonEmptyArray on success.
+*/
+declare const assertNonEmpty: <T>(arr: readonly T[], message?: string) => Result<NonEmptyArray<T>, InstanceType<typeof AssertionError>>;
+/**
+* Assert value matches a predicate.
+* Supports type guard predicates for narrowing.
+*/
+declare function assertMatches<
+	T,
+	U extends T
+>(value: T, predicate: (v: T) => v is U, message?: string): Result<U, InstanceType<typeof AssertionError>>;
+declare function assertMatches<T>(value: T, predicate: (v: T) => boolean, message?: string): Result<T, InstanceType<typeof AssertionError>>;
+/**
+* Assert a Result is Ok and return the narrowed value.
+*
+* Throws a descriptive error if the Result is Err, making it ideal for
+* test assertions with Bun's test runner.
+*
+* @param result - The Result to assert
+* @param message - Optional context message prepended to the error
+* @returns The unwrapped Ok value with type narrowing to `T`
+* @throws Error with descriptive message if Result is Err
+*
+* @example
+* ```typescript
+* import { expectOk } from "@outfitter/contracts";
+*
+* const result = await fetchUser(id);
+* const user = expectOk(result); // throws if Err, returns User if Ok
+* expect(user.name).toBe("Alice");
+* ```
+*/
+declare const expectOk: <
+	T,
+	E
+>(result: Result<T, E>, message?: string) => T;
+/**
+* Assert a Result is Err and return the narrowed error.
+*
+* Throws a descriptive error if the Result is Ok, making it ideal for
+* test assertions with Bun's test runner.
+*
+* @param result - The Result to assert
+* @param message - Optional context message prepended to the error
+* @returns The unwrapped Err value with type narrowing to `E`
+* @throws Error with descriptive message if Result is Ok
+*
+* @example
+* ```typescript
+* import { expectErr } from "@outfitter/contracts";
+*
+* const result = validateInput(invalidData);
+* const error = expectErr(result); // throws if Ok, returns error if Err
+* expect(error.category).toBe("validation");
+* ```
+*/
+declare const expectErr: <
+	T,
+	E
+>(result: Result<T, E>, message?: string) => E;
+export { NonEmptyArray, isNonEmptyArray, assertDefined, assertNonEmpty, assertMatches, expectOk, expectErr };

package/dist/shared/@outfitter/contracts-3re9d4bp.js

@@ -0,0 +1,114 @@
+// @bun
+// packages/contracts/src/internal/schema-primitives.ts
+function convertString(def) {
+  const schema = { type: "string" };
+  if (def.checks) {
+    for (const check of def.checks) {
+      const normalizedCheck = check?._zod?.def ?? check?.def ?? check;
+      if (normalizedCheck?.kind) {
+        switch (normalizedCheck.kind) {
+          case "min":
+            schema.minLength = normalizedCheck.value;
+            break;
+          case "max":
+            schema.maxLength = normalizedCheck.value;
+            break;
+          case "length":
+            schema.minLength = normalizedCheck.value;
+            schema.maxLength = normalizedCheck.value;
+            break;
+          case "email":
+            schema.pattern = "^[^@]+@[^@]+\\.[^@]+$";
+            break;
+          case "url":
+            schema.pattern = "^https?://";
+            break;
+          case "uuid":
+            schema.pattern = "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$";
+            break;
+          case "regex":
+            schema.pattern = normalizedCheck.regex?.source ?? normalizedCheck.pattern?.source ?? (typeof normalizedCheck.pattern === "string" ? normalizedCheck.pattern : undefined);
+            break;
+          default:
+            break;
+        }
+        continue;
+      }
+      if (!normalizedCheck?.check) {
+        continue;
+      }
+      switch (normalizedCheck.check) {
+        case "min_length":
+          schema.minLength = normalizedCheck.minimum;
+          break;
+        case "max_length":
+          schema.maxLength = normalizedCheck.maximum;
+          break;
+        case "string_format":
+          if (normalizedCheck.pattern) {
+            schema.pattern = typeof normalizedCheck.pattern === "string" ? normalizedCheck.pattern : normalizedCheck.pattern.source;
+          }
+          if (normalizedCheck.format && normalizedCheck.format !== "regex") {
+            schema.format = normalizedCheck.format;
+          }
+          break;
+        default:
+          break;
+      }
+    }
+  }
+  return schema;
+}
+function convertNumber(def) {
+  const schema = { type: "number" };
+  if (def.checks) {
+    for (const check of def.checks) {
+      const normalizedCheck = check?._zod?.def ?? check?.def ?? check;
+      if (normalizedCheck?.kind) {
+        switch (normalizedCheck.kind) {
+          case "min":
+            schema.minimum = normalizedCheck.value;
+            break;
+          case "max":
+            schema.maximum = normalizedCheck.value;
+            break;
+          case "int":
+            schema.type = "integer";
+            break;
+          default:
+            break;
+        }
+        continue;
+      }
+      if (!normalizedCheck?.check) {
+        continue;
+      }
+      switch (normalizedCheck.check) {
+        case "greater_than":
+          if (normalizedCheck.inclusive) {
+            schema.minimum = normalizedCheck.value;
+          } else {
+            schema.exclusiveMinimum = normalizedCheck.value;
+          }
+          break;
+        case "less_than":
+          if (normalizedCheck.inclusive) {
+            schema.maximum = normalizedCheck.value;
+          } else {
+            schema.exclusiveMaximum = normalizedCheck.value;
+          }
+          break;
+        case "number_format":
+          if (normalizedCheck.format === "int" || normalizedCheck.format === "safeint") {
+            schema.type = "integer";
+          }
+          break;
+        default:
+          break;
+      }
+    }
+  }
+  return schema;
+}
+
+export { convertString, convertNumber };

package/dist/shared/@outfitter/contracts-735ecmbq.d.ts

@@ -0,0 +1,107 @@
+import { AuthErrorBase, CancelledErrorBase, InternalErrorBase, NetworkErrorBase, PermissionErrorBase, RateLimitErrorBase, TimeoutErrorBase } from "./contracts-qpbv29bg.js";
+/**
+* Authorization denied.
+*
+* @example
+* ```typescript
+* new PermissionError({ message: "Cannot delete read-only resource" });
+* ```
+*/
+declare class PermissionError extends PermissionErrorBase {
+	readonly category: "permission";
+	/** Create a PermissionError with optional context. */
+	static create(message: string, context?: Record<string, unknown>): PermissionError;
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Operation timed out.
+*
+* @example
+* ```typescript
+* new TimeoutError({ message: "Database query timed out after 5000ms", operation: "Database query", timeoutMs: 5000 });
+* ```
+*/
+declare class TimeoutError extends TimeoutErrorBase {
+	readonly category: "timeout";
+	/** Create a TimeoutError with auto-generated message. */
+	static create(operation: string, timeoutMs: number): TimeoutError;
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Rate limit exceeded.
+*
+* @example
+* ```typescript
+* new RateLimitError({ message: "Rate limit exceeded, retry after 60s", retryAfterSeconds: 60 });
+* ```
+*/
+declare class RateLimitError extends RateLimitErrorBase {
+	readonly category: "rate_limit";
+	/** Create a RateLimitError with optional retry hint. */
+	static create(message: string, retryAfterSeconds?: number): RateLimitError;
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Network/transport failure.
+*
+* @example
+* ```typescript
+* new NetworkError({ message: "Connection refused to api.example.com" });
+* ```
+*/
+declare class NetworkError extends NetworkErrorBase {
+	readonly category: "network";
+	/** Create a NetworkError with optional context. */
+	static create(message: string, context?: Record<string, unknown>): NetworkError;
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Unexpected internal error.
+*
+* @example
+* ```typescript
+* new InternalError({ message: "Unexpected state in processor" });
+* ```
+*/
+declare class InternalError extends InternalErrorBase {
+	readonly category: "internal";
+	/** Create an InternalError with optional context. */
+	static create(message: string, context?: Record<string, unknown>): InternalError;
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Authentication failed (missing or invalid credentials).
+*
+* @example
+* ```typescript
+* new AuthError({ message: "Invalid API key", reason: "invalid" });
+* ```
+*/
+declare class AuthError extends AuthErrorBase {
+	readonly category: "auth";
+	/** Create an AuthError with optional reason. */
+	static create(message: string, reason?: "missing" | "invalid" | "expired"): AuthError;
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Operation cancelled by user or signal.
+*
+* @example
+* ```typescript
+* new CancelledError({ message: "Operation cancelled by user" });
+* ```
+*/
+declare class CancelledError extends CancelledErrorBase {
+	readonly category: "cancelled";
+	/** Create a CancelledError. */
+	static create(message: string): CancelledError;
+	exitCode(): number;
+	statusCode(): number;
+}
+export { PermissionError, TimeoutError, RateLimitError, NetworkError, InternalError, AuthError, CancelledError };

package/dist/shared/@outfitter/contracts-7a0xmwbg.d.ts

@@ -0,0 +1,11 @@
+import { AuthError, CancelledError, InternalError, NetworkError, PermissionError, RateLimitError, TimeoutError } from "./contracts-735ecmbq.js";
+import { AlreadyExistsError, AmbiguousError, AssertionError, ConflictError, NotFoundError, ValidationError } from "./contracts-mehpmvwp.js";
+/**
+* Canonical union type of all concrete error class instances.
+*/
+type OutfitterError = InstanceType<typeof ValidationError> | InstanceType<typeof AmbiguousError> | InstanceType<typeof AssertionError> | InstanceType<typeof NotFoundError> | InstanceType<typeof AlreadyExistsError> | InstanceType<typeof ConflictError> | InstanceType<typeof PermissionError> | InstanceType<typeof TimeoutError> | InstanceType<typeof RateLimitError> | InstanceType<typeof NetworkError> | InstanceType<typeof InternalError> | InstanceType<typeof AuthError> | InstanceType<typeof CancelledError>;
+/**
+* @deprecated Use `OutfitterError` instead. This alias will be removed in v1.0.
+*/
+type AnyKitError = OutfitterError;
+export { OutfitterError, AnyKitError };

package/dist/shared/@outfitter/contracts-8cmkh2db.d.ts

@@ -0,0 +1,31 @@
+import { JsonSchema } from "./contracts-w7nvcwrp.js";
+import { z } from "zod";
+/**
+* Convert a Zod schema to JSON Schema format.
+*
+* This is a simplified converter that handles common Zod types.
+* For complex schemas, consider using a full zod-to-json-schema library.
+*
+* @param schema - Zod schema to convert
+* @returns JSON Schema representation
+*
+* @example
+* ```typescript
+* const zodSchema = z.object({
+*   name: z.string(),
+*   age: z.number().optional(),
+* });
+*
+* const jsonSchema = zodToJsonSchema(zodSchema);
+* // {
+* //   type: "object",
+* //   properties: {
+* //     name: { type: "string" },
+* //     age: { type: "number" },
+* //   },
+* //   required: ["name"],
+* // }
+* ```
+*/
+declare function zodToJsonSchema(schema: z.ZodType<unknown>): JsonSchema;
+export { zodToJsonSchema };

package/dist/shared/@outfitter/{contracts-agmt8915.js → contracts-c3qfce25.js}

@@ -22,6 +22,9 @@ function createContext(options) {
   if (options.signal !== undefined) {
     ctx.signal = options.signal;
   }
+  if (options.progress !== undefined) {
+    ctx.progress = options.progress;
+  }
   if (options.workspaceRoot !== undefined) {
     ctx.workspaceRoot = options.workspaceRoot;
   }