@ontrails/core 1.0.0-beta.0

package/src/errors.ts

@@ -0,0 +1,196 @@
+/* oxlint-disable max-classes-per-file -- error taxonomy requires co-located class definitions */
+/**
+ * Error taxonomy for @ontrails/core
+ *
+ * Provides a structured error hierarchy with category-based mapping
+ * to exit codes, HTTP status codes, and JSON-RPC error codes.
+ */
+
+// ---------------------------------------------------------------------------
+// Category
+// ---------------------------------------------------------------------------
+
+export type ErrorCategory =
+  | 'validation'
+  | 'not_found'
+  | 'conflict'
+  | 'permission'
+  | 'timeout'
+  | 'rate_limit'
+  | 'network'
+  | 'internal'
+  | 'auth'
+  | 'cancelled';
+
+// ---------------------------------------------------------------------------
+// Base class
+// ---------------------------------------------------------------------------
+
+export abstract class TrailsError extends Error {
+  abstract readonly category: ErrorCategory;
+  abstract readonly retryable: boolean;
+  readonly context?: Record<string, unknown> | undefined;
+
+  constructor(
+    message: string,
+    options?: { cause?: Error; context?: Record<string, unknown> }
+  ) {
+    super(message, { cause: options?.cause });
+    this.name = this.constructor.name;
+    this.context = options?.context;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Concrete error classes
+// ---------------------------------------------------------------------------
+
+export class ValidationError extends TrailsError {
+  readonly category = 'validation' as const;
+  readonly retryable = false as const;
+}
+
+export class AmbiguousError extends TrailsError {
+  readonly category = 'validation' as const;
+  readonly retryable = false as const;
+}
+
+export class AssertionError extends TrailsError {
+  readonly category = 'internal' as const;
+  readonly retryable = false as const;
+}
+
+export class NotFoundError extends TrailsError {
+  readonly category = 'not_found' as const;
+  readonly retryable = false as const;
+}
+
+export class AlreadyExistsError extends TrailsError {
+  readonly category = 'conflict' as const;
+  readonly retryable = false as const;
+}
+
+export class ConflictError extends TrailsError {
+  readonly category = 'conflict' as const;
+  readonly retryable = false as const;
+}
+
+export class PermissionError extends TrailsError {
+  readonly category = 'permission' as const;
+  readonly retryable = false as const;
+}
+
+export class TimeoutError extends TrailsError {
+  readonly category = 'timeout' as const;
+  readonly retryable = true as const;
+}
+
+export class RateLimitError extends TrailsError {
+  readonly category = 'rate_limit' as const;
+  readonly retryable = true as const;
+  readonly retryAfter?: number | undefined;
+
+  constructor(
+    message: string,
+    options?: {
+      cause?: Error;
+      context?: Record<string, unknown>;
+      retryAfter?: number;
+    }
+  ) {
+    super(message, options);
+    this.retryAfter = options?.retryAfter;
+  }
+}
+
+export class NetworkError extends TrailsError {
+  readonly category = 'network' as const;
+  readonly retryable = true as const;
+}
+
+export class InternalError extends TrailsError {
+  readonly category = 'internal' as const;
+  readonly retryable = false as const;
+}
+
+export class AuthError extends TrailsError {
+  readonly category = 'auth' as const;
+  readonly retryable = false as const;
+}
+
+export class CancelledError extends TrailsError {
+  readonly category = 'cancelled' as const;
+  readonly retryable = false as const;
+}
+
+// ---------------------------------------------------------------------------
+// Taxonomy maps
+// ---------------------------------------------------------------------------
+
+export const exitCodeMap: Record<ErrorCategory, number> = {
+  auth: 9,
+  cancelled: 130,
+  conflict: 3,
+  internal: 8,
+  network: 7,
+  not_found: 2,
+  permission: 4,
+  rate_limit: 6,
+  timeout: 5,
+  validation: 1,
+} as const;
+
+export const statusCodeMap: Record<ErrorCategory, number> = {
+  auth: 401,
+  cancelled: 499,
+  conflict: 409,
+  internal: 500,
+  network: 502,
+  not_found: 404,
+  permission: 403,
+  rate_limit: 429,
+  timeout: 504,
+  validation: 400,
+} as const;
+
+export const jsonRpcCodeMap: Record<ErrorCategory, number> = {
+  auth: -32_600,
+  cancelled: -32_603,
+  conflict: -32_603,
+  internal: -32_603,
+  network: -32_603,
+  not_found: -32_601,
+  permission: -32_600,
+  rate_limit: -32_603,
+  timeout: -32_603,
+  validation: -32_602,
+} as const;
+
+export const retryableMap: Record<ErrorCategory, boolean> = {
+  auth: false,
+  cancelled: false,
+  conflict: false,
+  internal: false,
+  network: true,
+  not_found: false,
+  permission: false,
+  rate_limit: true,
+  timeout: true,
+  validation: false,
+} as const;
+
+// ---------------------------------------------------------------------------
+// Helper functions
+// ---------------------------------------------------------------------------
+
+/** Type guard: narrows unknown to TrailsError */
+export const isTrailsError = (error?: unknown): error is TrailsError =>
+  error instanceof TrailsError;
+
+/** Returns true if the error is retryable (TrailsError with retryable category). */
+export const isRetryable = (error: Error): boolean => {
+  if (isTrailsError(error)) {
+    return retryableMap[error.category];
+  }
+  return false;
+};

package/src/event.ts

@@ -0,0 +1,77 @@
+/**
+ * Event — a named payload schema with optional provenance metadata.
+ */
+
+import type { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Spec (input to the factory)
+// ---------------------------------------------------------------------------
+
+export interface EventSpec<T> {
+  readonly payload: z.ZodType<T>;
+  readonly description?: string | undefined;
+  readonly markers?: Readonly<Record<string, unknown>> | undefined;
+  /** Trail IDs that produce this event (e.g. the trails it originates from). */
+  readonly from?: readonly string[] | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Shape (output of the factory)
+// ---------------------------------------------------------------------------
+
+export interface Event<T> {
+  readonly id: string;
+  readonly kind: 'event';
+  readonly payload: z.ZodType<T>;
+  readonly description?: string | undefined;
+  readonly markers?: Readonly<Record<string, unknown>> | undefined;
+  /** Trail IDs that produce this event (e.g. the trails it originates from). */
+  readonly from?: readonly string[] | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an event definition.
+ *
+ * An event is a named payload schema describing something that happened.
+ * Returns a frozen object with `kind: "event"` and all spec fields.
+ *
+ * @example
+ * ```typescript
+ * // ID as first argument
+ * const updated = event("entity.updated", {
+ *   payload: EntityUpdatedSchema,
+ *   from: ["entity.add", "entity.update"],
+ * });
+ *
+ * // Full spec object (programmatic)
+ * const updated = event({ id: "entity.updated", payload: ..., from: [...] });
+ * ```
+ */
+export function event<T>(id: string, spec: EventSpec<T>): Event<T>;
+export function event<T>(
+  spec: EventSpec<T> & { readonly id: string }
+): Event<T>;
+export function event<T>(
+  idOrSpec: string | (EventSpec<T> & { readonly id: string }),
+  maybeSpec?: EventSpec<T>
+): Event<T> {
+  const resolvedId = typeof idOrSpec === 'string' ? idOrSpec : idOrSpec.id;
+  // oxlint-disable-next-line no-non-null-assertion -- overload guarantees maybeSpec when idOrSpec is string
+  const resolvedSpec = typeof idOrSpec === 'string' ? maybeSpec! : idOrSpec;
+  return Object.freeze({
+    description: resolvedSpec.description,
+    from: resolvedSpec.from ? Object.freeze([...resolvedSpec.from]) : undefined,
+    id: resolvedId,
+    kind: 'event' as const,
+    markers: resolvedSpec.markers,
+    payload: resolvedSpec.payload,
+  });
+}
+
+/** Existential type for heterogeneous event collections */
+export type AnyEvent = Event<unknown>;

package/src/fetch.ts

@@ -0,0 +1,138 @@
+/**
+ * Fetch utilities for @ontrails/core
+ *
+ * Wraps the standard fetch API, mapping errors and HTTP status codes
+ * to the TrailsError taxonomy.
+ */
+
+import {
+  AuthError,
+  CancelledError,
+  ConflictError,
+  InternalError,
+  NetworkError,
+  NotFoundError,
+  PermissionError,
+  RateLimitError,
+  TimeoutError,
+  ValidationError,
+} from './errors.js';
+import { Result } from './result.js';
+
+// ---------------------------------------------------------------------------
+// Internal helpers (defined before usage)
+// ---------------------------------------------------------------------------
+
+const toError = (err: unknown): Error =>
+  err instanceof Error ? err : new Error(String(err));
+
+const parseRetryAfter = (header: string | null): number | undefined => {
+  if (!header) {
+    return undefined;
+  }
+  const seconds = Number(header);
+  if (Number.isFinite(seconds) && seconds > 0) {
+    return seconds;
+  }
+  // Try parsing as HTTP-date
+  const date = Date.parse(header);
+  if (!Number.isNaN(date)) {
+    const delta = Math.ceil((date - Date.now()) / 1000);
+    return delta > 0 ? delta : undefined;
+  }
+  return undefined;
+};
+
+const mapFetchError = (err: unknown): Error => {
+  if (err instanceof DOMException && err.name === 'AbortError') {
+    return new CancelledError('Request was aborted', { cause: toError(err) });
+  }
+
+  // TypeError is thrown for network failures in the fetch spec
+  if (err instanceof TypeError) {
+    return new NetworkError('Network request failed', { cause: err });
+  }
+
+  return new NetworkError('Network request failed', {
+    cause: toError(err),
+  });
+};
+
+type StatusMapper = (
+  context: Record<string, unknown>,
+  response: Response
+) => Error;
+
+const statusMappers: Record<number, StatusMapper> = {
+  401: (ctx) => new AuthError('Unauthorized', { context: ctx }),
+  403: (ctx) => new PermissionError('Forbidden', { context: ctx }),
+  404: (ctx) => new NotFoundError('Not found', { context: ctx }),
+  429: (ctx, response) => {
+    const retryAfter = parseRetryAfter(response.headers.get('retry-after'));
+    const opts: { context: Record<string, unknown>; retryAfter?: number } = {
+      context: ctx,
+    };
+    if (retryAfter !== undefined) {
+      opts.retryAfter = retryAfter;
+    }
+    return new RateLimitError('Rate limited', opts);
+  },
+  500: (ctx) => new InternalError('Internal server error', { context: ctx }),
+  502: (ctx) => new NetworkError('Bad gateway', { context: ctx }),
+  504: (ctx) => new TimeoutError('Gateway timeout', { context: ctx }),
+};
+
+/** Map 4xx status codes not in the explicit mapper to appropriate error types. */
+const mapClientError = (
+  status: number,
+  context: Record<string, unknown>
+): Error => {
+  if (status === 400 || status === 422) {
+    return new ValidationError(`Validation error (${status})`, { context });
+  }
+  if (status === 409) {
+    return new ConflictError(`Conflict (${status})`, { context });
+  }
+  return new InternalError(`HTTP error (${status})`, { context });
+};
+
+const mapStatusCode = (response: Response): Error => {
+  const context = { status: response.status, url: response.url };
+  const mapper = statusMappers[response.status];
+  if (mapper) {
+    return mapper(context, response);
+  }
+  if (response.status >= 500) {
+    return new InternalError(`Server error (${response.status})`, { context });
+  }
+  return mapClientError(response.status, context);
+};
+
+// ---------------------------------------------------------------------------
+// fromFetch
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap a fetch call in a Result, mapping failures to TrailsError subclasses.
+ *
+ * Network errors become NetworkError. Abort signals become CancelledError.
+ * HTTP error status codes map to the appropriate error category.
+ */
+export const fromFetch = async (
+  input: string | URL | Request,
+  init?: RequestInit
+): Promise<Result<Response, Error>> => {
+  let response: Response;
+
+  try {
+    response = await fetch(input, init);
+  } catch (error) {
+    return Result.err(mapFetchError(error));
+  }
+
+  if (response.ok) {
+    return Result.ok(response);
+  }
+
+  return Result.err(mapStatusCode(response));
+};

package/src/guards.ts

@@ -0,0 +1,37 @@
+/**
+ * Type guards and assertion helpers for @ontrails/core.
+ */
+
+/** Narrows `T | null | undefined` to `T`. */
+export const isDefined = <T>(value?: T | null | undefined): value is T =>
+  value !== null && value !== undefined;
+
+/** Returns true when `value` is a string with length > 0. */
+export const isNonEmptyString = (value?: unknown): value is string =>
+  typeof value === 'string' && value.length > 0;
+
+/** Returns true when `value` is a plain object (not an array, Date, etc.). */
+export const isPlainObject = (
+  value: unknown
+): value is Record<string, unknown> => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(value) as unknown;
+  return proto === Object.prototype || proto === null;
+};
+
+/** Checks that `obj` is an object with the given key present. */
+export const hasProperty = <K extends string>(
+  obj: unknown,
+  key: K
+): obj is Record<K, unknown> =>
+  typeof obj === 'object' && obj !== null && key in obj;
+
+/**
+ * Exhaustive switch helper. Place in the `default` branch to get a compile
+ * error when a union case is unhandled.
+ */
+export const assertNever = (value: never): never => {
+  throw new Error(`Unexpected value: ${String(value)}`);
+};

package/src/health.ts

@@ -0,0 +1,23 @@
+// ---------------------------------------------------------------------------
+// Health check types
+// ---------------------------------------------------------------------------
+
+/** Aggregate health status */
+export type HealthStatus = 'healthy' | 'degraded' | 'unhealthy';
+
+/** Individual component check result */
+export interface HealthCheck {
+  readonly status: HealthStatus;
+  readonly message?: string | undefined;
+  /** Latency in milliseconds */
+  readonly latency?: number | undefined;
+}
+
+/** Full health report returned by a health endpoint */
+export interface HealthResult {
+  readonly status: HealthStatus;
+  readonly checks: Readonly<Record<string, HealthCheck>>;
+  readonly version?: string | undefined;
+  /** Uptime in seconds */
+  readonly uptime?: number | undefined;
+}

package/src/hike.ts

@@ -0,0 +1,77 @@
+/**
+ * Hike — a composition that follows trails.
+ */
+
+import type { Trail, TrailSpec } from './trail.js';
+import type { TrailContext } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Spec (input to the factory)
+// ---------------------------------------------------------------------------
+
+export interface HikeSpec<I, O> extends TrailSpec<I, O> {
+  readonly follows: readonly string[];
+}
+
+// ---------------------------------------------------------------------------
+// Shape (output of the factory)
+// ---------------------------------------------------------------------------
+
+export interface Hike<I, O> extends Omit<Trail<I, O>, 'kind'> {
+  readonly kind: 'hike';
+  readonly follows: readonly string[];
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a hike definition.
+ *
+ * A hike is a composition that declares which trails it follows.
+ * Returns a frozen object with `kind: "hike"` and all spec fields.
+ *
+ * @example
+ * ```typescript
+ * // ID as first argument
+ * const onboard = hike("entity.onboard", {
+ *   follows: ["entity.add", "entity.relate"],
+ *   input: z.object({ name: z.string() }),
+ *   implementation: (input, ctx) => Result.ok(...),
+ * });
+ *
+ * // Full spec object (programmatic)
+ * const onboard = hike({ id: "entity.onboard", follows: [...], ... });
+ * ```
+ */
+export function hike<I, O>(id: string, spec: HikeSpec<I, O>): Hike<I, O>;
+export function hike<I, O>(
+  spec: HikeSpec<I, O> & { readonly id: string }
+): Hike<I, O>;
+export function hike<I, O>(
+  idOrSpec: string | (HikeSpec<I, O> & { readonly id: string }),
+  maybeSpec?: HikeSpec<I, O>
+): Hike<I, O> {
+  const resolved =
+    typeof idOrSpec === 'string'
+      ? { id: idOrSpec, spec: maybeSpec }
+      : { id: idOrSpec.id, spec: idOrSpec };
+
+  if (!resolved.spec) {
+    throw new TypeError('hike() requires a spec when an id is provided');
+  }
+
+  const { follows, implementation, ...rest } = resolved.spec;
+  return Object.freeze({
+    ...rest,
+    follows: Object.freeze([...follows]),
+    id: resolved.id,
+    implementation: async (input: I, ctx: TrailContext) =>
+      await implementation(input, ctx),
+    kind: 'hike' as const,
+  });
+}
+
+// oxlint-disable-next-line no-explicit-any -- existential type; see AnyTrail
+export type AnyHike = Hike<any, any>;

package/src/index.ts

@@ -0,0 +1,158 @@
+// Result
+export { Result } from './result.js';
+
+// Errors
+export {
+  TrailsError,
+  ValidationError,
+  AmbiguousError,
+  AssertionError,
+  NotFoundError,
+  AlreadyExistsError,
+  ConflictError,
+  PermissionError,
+  TimeoutError,
+  RateLimitError,
+  NetworkError,
+  InternalError,
+  AuthError,
+  CancelledError,
+  exitCodeMap,
+  statusCodeMap,
+  jsonRpcCodeMap,
+  retryableMap,
+  isRetryable,
+  isTrailsError,
+} from './errors.js';
+export type { ErrorCategory } from './errors.js';
+
+// Types
+export type {
+  Implementation,
+  TrailContext,
+  FollowFn,
+  ProgressCallback,
+  ProgressEvent,
+  Logger,
+  Surface,
+} from './types.js';
+
+// Context factory
+export { createTrailContext } from './context.js';
+
+// Trail
+export { trail } from './trail.js';
+export type { AnyTrail, Trail, TrailSpec, TrailExample } from './trail.js';
+
+// Hike
+export { hike } from './hike.js';
+export type { AnyHike, Hike, HikeSpec } from './hike.js';
+
+// Event
+export { event } from './event.js';
+export type { AnyEvent, Event, EventSpec } from './event.js';
+
+// Topo
+export { topo } from './topo.js';
+export type { Topo } from './topo.js';
+
+// Topo validation
+export { validateTopo } from './validate-topo.js';
+export type { TopoIssue } from './validate-topo.js';
+
+// Layer
+export { composeLayers } from './layer.js';
+export type { Layer } from './layer.js';
+
+// Health
+export type { HealthStatus, HealthResult } from './health.js';
+
+// Adapters
+export type {
+  IndexAdapter,
+  StorageAdapter,
+  CacheAdapter,
+  SearchOptions,
+  SearchResult,
+  StorageOptions,
+} from './adapters.js';
+
+// Derive
+export { deriveFields } from './derive.js';
+export type { Field, FieldOverride } from './derive.js';
+
+// Validation
+export {
+  validateInput,
+  validateOutput,
+  formatZodIssues,
+  zodToJsonSchema,
+} from './validation.js';
+
+// Serialization
+export { serializeError, deserializeError } from './serialization.js';
+export type { SerializedError } from './serialization.js';
+
+// Resilience
+export {
+  retry,
+  withTimeout,
+  shouldRetry,
+  getBackoffDelay,
+} from './resilience.js';
+export type { RetryOptions } from './resilience.js';
+
+// Fetch — fromFetch is available as Result.fromFetch()
+
+// Branded types
+export {
+  brand,
+  unbrand,
+  uuid,
+  email,
+  nonEmptyString,
+  positiveInt,
+  shortId,
+  hashId,
+} from './branded.js';
+export type {
+  Branded,
+  UUID,
+  Email,
+  NonEmptyString,
+  PositiveInt,
+} from './branded.js';
+
+// Path Security
+export { securePath, isPathSafe, resolveSafePath } from './path-security.js';
+
+// Workspace
+export {
+  findWorkspaceRoot,
+  isInsideWorkspace,
+  getRelativePath,
+} from './workspace.js';
+
+// Guards
+export {
+  isDefined,
+  isNonEmptyString,
+  isPlainObject,
+  hasProperty,
+  assertNever,
+} from './guards.js';
+
+// Collections
+export {
+  chunk,
+  dedupe,
+  groupBy,
+  sortBy,
+  isNonEmptyArray,
+} from './collections.js';
+export type {
+  NonEmptyArray,
+  DeepPartial,
+  Prettify,
+  AtLeastOne,
+} from './collections.js';