@ontrails/core 1.0.0-beta.0

package/dist/derive.js

@@ -0,0 +1,122 @@
+/**
+ * Schema-driven field derivation for @ontrails/core
+ *
+ * Introspects Zod v4 schemas to produce a surface-agnostic Field[] descriptor
+ * that UI layers (CLI prompts, web forms, etc.) can consume.
+ */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Convert camelCase / PascalCase to "Title Case" label. */
+const humanize = (str) => str
+    .replaceAll(/([a-z])([A-Z])/g, '$1 $2')
+    .replaceAll(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .replace(/^./, (ch) => ch.toUpperCase());
+/** Get the inner type from an optional or default wrapper. */
+const getInnerType = (current) => current._zod.def['innerType'];
+/** Propagate description from inner to state if present. */
+const propagateDescription = (inner, state) => {
+    if (inner.description) {
+        state.description = inner.description;
+    }
+};
+/** Step one level of optional/default unwrapping. Returns null if not a wrapper type. */
+const unwrapStep = (current, state) => {
+    const defType = current._zod.def['type'];
+    if (defType !== 'optional' && defType !== 'default') {
+        return null;
+    }
+    state.required = false;
+    if (defType === 'default') {
+        state.defaultValue = current._zod.def['defaultValue'];
+    }
+    const inner = getInnerType(current);
+    propagateDescription(inner, state);
+    return inner;
+};
+/** Unwrap optional / default wrappers, collecting metadata. */
+const unwrap = (s) => {
+    const state = {
+        defaultValue: undefined,
+        description: s.description,
+        required: true,
+    };
+    let current = s;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        const next = unwrapStep(current, state);
+        if (next === null) {
+            break;
+        }
+        current = next;
+    }
+    return { ...state, inner: current };
+};
+const fieldTypeByDef = {
+    array: (s) => {
+        const element = s._zod.def['element'];
+        const elementType = element._zod.def['type'];
+        if (elementType === 'enum') {
+            const entries = element._zod.def['entries'];
+            return { options: Object.values(entries), type: 'multiselect' };
+        }
+        return { options: undefined, type: 'string' };
+    },
+    boolean: () => ({ options: undefined, type: 'boolean' }),
+    enum: (s) => {
+        const entries = s._zod.def['entries'];
+        return { options: Object.values(entries), type: 'enum' };
+    },
+    number: () => ({ options: undefined, type: 'number' }),
+    string: () => ({ options: undefined, type: 'string' }),
+};
+/** Derive field type and raw options from the unwrapped Zod def. */
+const deriveFieldType = (s) => {
+    const defType = s._zod.def['type'];
+    const derive = fieldTypeByDef[defType];
+    return derive ? derive(s) : { options: undefined, type: 'string' };
+};
+/** Build options array, merging with overrides when present. */
+const buildOptions = (rawOptions, overrideOptions) => {
+    if (!rawOptions) {
+        return undefined;
+    }
+    if (!overrideOptions) {
+        return rawOptions.map((v) => ({ value: v }));
+    }
+    const overrideMap = new Map(overrideOptions.map((o) => [o.value, o]));
+    return rawOptions.map((v) => {
+        const ov = overrideMap.get(v);
+        return ov ? { hint: ov.hint, label: ov.label, value: v } : { value: v };
+    });
+};
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Derive a surface-agnostic Field[] from a Zod object schema.
+ *
+ * Uses Zod v4's `_zod.def` for introspection. Returns fields sorted by name.
+ */
+/** Derive a single field from a shape entry. */
+const deriveField = (key, value, overrides) => {
+    const { inner, required, defaultValue, description } = unwrap(value);
+    const { type, options: rawOptions } = deriveFieldType(inner);
+    const override = overrides?.[key];
+    const label = override?.label ?? description ?? humanize(key);
+    const options = buildOptions(rawOptions, override?.options);
+    return { default: defaultValue, label, name: key, options, required, type };
+};
+export const deriveFields = (schema, overrides) => {
+    const s = schema;
+    if (s._zod.def['type'] !== 'object') {
+        return [];
+    }
+    const shape = s._zod.def['shape'];
+    if (!shape) {
+        return [];
+    }
+    const fields = Object.entries(shape).map(([key, value]) => deriveField(key, value, overrides));
+    return fields.toSorted((a, b) => a.name.localeCompare(b.name));
+};
+//# sourceMappingURL=derive.js.map

package/dist/derive.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 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.
+ */
+export type ErrorCategory = 'validation' | 'not_found' | 'conflict' | 'permission' | 'timeout' | 'rate_limit' | 'network' | 'internal' | 'auth' | 'cancelled';
+export declare 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>;
+    });
+}
+export declare class ValidationError extends TrailsError {
+    readonly category: "validation";
+    readonly retryable: false;
+}
+export declare class AmbiguousError extends TrailsError {
+    readonly category: "validation";
+    readonly retryable: false;
+}
+export declare class AssertionError extends TrailsError {
+    readonly category: "internal";
+    readonly retryable: false;
+}
+export declare class NotFoundError extends TrailsError {
+    readonly category: "not_found";
+    readonly retryable: false;
+}
+export declare class AlreadyExistsError extends TrailsError {
+    readonly category: "conflict";
+    readonly retryable: false;
+}
+export declare class ConflictError extends TrailsError {
+    readonly category: "conflict";
+    readonly retryable: false;
+}
+export declare class PermissionError extends TrailsError {
+    readonly category: "permission";
+    readonly retryable: false;
+}
+export declare class TimeoutError extends TrailsError {
+    readonly category: "timeout";
+    readonly retryable: true;
+}
+export declare class RateLimitError extends TrailsError {
+    readonly category: "rate_limit";
+    readonly retryable: true;
+    readonly retryAfter?: number | undefined;
+    constructor(message: string, options?: {
+        cause?: Error;
+        context?: Record<string, unknown>;
+        retryAfter?: number;
+    });
+}
+export declare class NetworkError extends TrailsError {
+    readonly category: "network";
+    readonly retryable: true;
+}
+export declare class InternalError extends TrailsError {
+    readonly category: "internal";
+    readonly retryable: false;
+}
+export declare class AuthError extends TrailsError {
+    readonly category: "auth";
+    readonly retryable: false;
+}
+export declare class CancelledError extends TrailsError {
+    readonly category: "cancelled";
+    readonly retryable: false;
+}
+export declare const exitCodeMap: Record<ErrorCategory, number>;
+export declare const statusCodeMap: Record<ErrorCategory, number>;
+export declare const jsonRpcCodeMap: Record<ErrorCategory, number>;
+export declare const retryableMap: Record<ErrorCategory, boolean>;
+/** Type guard: narrows unknown to TrailsError */
+export declare const isTrailsError: (error?: unknown) => error is TrailsError;
+/** Returns true if the error is retryable (TrailsError with retryable category). */
+export declare const isRetryable: (error: Error) => boolean;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

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

package/dist/errors.js

@@ -0,0 +1,142 @@
+/* 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.
+ */
+// ---------------------------------------------------------------------------
+// Base class
+// ---------------------------------------------------------------------------
+export class TrailsError extends Error {
+    context;
+    constructor(message, options) {
+        super(message, { cause: options?.cause });
+        this.name = this.constructor.name;
+        this.context = options?.context;
+    }
+}
+// ---------------------------------------------------------------------------
+// Concrete error classes
+// ---------------------------------------------------------------------------
+export class ValidationError extends TrailsError {
+    category = 'validation';
+    retryable = false;
+}
+export class AmbiguousError extends TrailsError {
+    category = 'validation';
+    retryable = false;
+}
+export class AssertionError extends TrailsError {
+    category = 'internal';
+    retryable = false;
+}
+export class NotFoundError extends TrailsError {
+    category = 'not_found';
+    retryable = false;
+}
+export class AlreadyExistsError extends TrailsError {
+    category = 'conflict';
+    retryable = false;
+}
+export class ConflictError extends TrailsError {
+    category = 'conflict';
+    retryable = false;
+}
+export class PermissionError extends TrailsError {
+    category = 'permission';
+    retryable = false;
+}
+export class TimeoutError extends TrailsError {
+    category = 'timeout';
+    retryable = true;
+}
+export class RateLimitError extends TrailsError {
+    category = 'rate_limit';
+    retryable = true;
+    retryAfter;
+    constructor(message, options) {
+        super(message, options);
+        this.retryAfter = options?.retryAfter;
+    }
+}
+export class NetworkError extends TrailsError {
+    category = 'network';
+    retryable = true;
+}
+export class InternalError extends TrailsError {
+    category = 'internal';
+    retryable = false;
+}
+export class AuthError extends TrailsError {
+    category = 'auth';
+    retryable = false;
+}
+export class CancelledError extends TrailsError {
+    category = 'cancelled';
+    retryable = false;
+}
+// ---------------------------------------------------------------------------
+// Taxonomy maps
+// ---------------------------------------------------------------------------
+export const exitCodeMap = {
+    auth: 9,
+    cancelled: 130,
+    conflict: 3,
+    internal: 8,
+    network: 7,
+    not_found: 2,
+    permission: 4,
+    rate_limit: 6,
+    timeout: 5,
+    validation: 1,
+};
+export const statusCodeMap = {
+    auth: 401,
+    cancelled: 499,
+    conflict: 409,
+    internal: 500,
+    network: 502,
+    not_found: 404,
+    permission: 403,
+    rate_limit: 429,
+    timeout: 504,
+    validation: 400,
+};
+export const jsonRpcCodeMap = {
+    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,
+};
+export const retryableMap = {
+    auth: false,
+    cancelled: false,
+    conflict: false,
+    internal: false,
+    network: true,
+    not_found: false,
+    permission: false,
+    rate_limit: true,
+    timeout: true,
+    validation: false,
+};
+// ---------------------------------------------------------------------------
+// Helper functions
+// ---------------------------------------------------------------------------
+/** Type guard: narrows unknown to TrailsError */
+export const isTrailsError = (error) => error instanceof TrailsError;
+/** Returns true if the error is retryable (TrailsError with retryable category). */
+export const isRetryable = (error) => {
+    if (isTrailsError(error)) {
+        return retryableMap[error.category];
+    }
+    return false;
+};
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/event.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Event — a named payload schema with optional provenance metadata.
+ */
+import type { z } from 'zod';
+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;
+}
+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;
+}
+/**
+ * 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 declare function event<T>(id: string, spec: EventSpec<T>): Event<T>;
+export declare function event<T>(spec: EventSpec<T> & {
+    readonly id: string;
+}): Event<T>;
+/** Existential type for heterogeneous event collections */
+export type AnyEvent = Event<unknown>;
+//# sourceMappingURL=event.d.ts.map

package/dist/event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../src/event.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAM7B,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IACjE,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC/C;AAMD,MAAM,WAAW,KAAK,CAAC,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IACjE,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC/C;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;AACnE,wBAAgB,KAAK,CAAC,CAAC,EACrB,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC3C,KAAK,CAAC,CAAC,CAAC,CAAC;AAkBZ,2DAA2D;AAC3D,MAAM,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC"}

package/dist/event.js

@@ -0,0 +1,17 @@
+/**
+ * Event — a named payload schema with optional provenance metadata.
+ */
+export function event(idOrSpec, maybeSpec) {
+    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',
+        markers: resolvedSpec.markers,
+        payload: resolvedSpec.payload,
+    });
+}
+//# sourceMappingURL=event.js.map

package/dist/event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.js","sourceRoot":"","sources":["../src/event.ts"],"names":[],"mappings":"AAAA;;GAEG;AAwDH,MAAM,UAAU,KAAK,CACnB,QAA2D,EAC3D,SAAwB;IAExB,MAAM,UAAU,GAAG,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;IACzE,0GAA0G;IAC1G,MAAM,YAAY,GAAG,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAU,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC1E,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,WAAW,EAAE,YAAY,CAAC,WAAW;QACrC,IAAI,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS;QAC3E,EAAE,EAAE,UAAU;QACd,IAAI,EAAE,OAAgB;QACtB,OAAO,EAAE,YAAY,CAAC,OAAO;QAC7B,OAAO,EAAE,YAAY,CAAC,OAAO;KAC9B,CAAC,CAAC;AACL,CAAC"}

package/dist/fetch.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Fetch utilities for @ontrails/core
+ *
+ * Wraps the standard fetch API, mapping errors and HTTP status codes
+ * to the TrailsError taxonomy.
+ */
+import { Result } from './result.js';
+/**
+ * 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 declare const fromFetch: (input: string | URL | Request, init?: RequestInit) => Promise<Result<Response, Error>>;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../src/fetch.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAcH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AA+FrC;;;;;GAKG;AACH,eAAO,MAAM,SAAS,GACpB,OAAO,MAAM,GAAG,GAAG,GAAG,OAAO,EAC7B,OAAO,WAAW,KACjB,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,CAcjC,CAAC"}

package/dist/fetch.js

@@ -0,0 +1,102 @@
+/**
+ * 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) => err instanceof Error ? err : new Error(String(err));
+const parseRetryAfter = (header) => {
+    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) => {
+    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),
+    });
+};
+const statusMappers = {
+    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: 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, context) => {
+    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) => {
+    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, init) => {
+    let 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));
+};
+//# sourceMappingURL=fetch.js.map

package/dist/fetch.js.map

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

package/dist/guards.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Type guards and assertion helpers for @ontrails/core.
+ */
+/** Narrows `T | null | undefined` to `T`. */
+export declare const isDefined: <T>(value?: T | null | undefined) => value is T;
+/** Returns true when `value` is a string with length > 0. */
+export declare const isNonEmptyString: (value?: unknown) => value is string;
+/** Returns true when `value` is a plain object (not an array, Date, etc.). */
+export declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
+/** Checks that `obj` is an object with the given key present. */
+export declare const hasProperty: <K extends string>(obj: unknown, key: K) => obj is Record<K, unknown>;
+/**
+ * Exhaustive switch helper. Place in the `default` branch to get a compile
+ * error when a union case is unhandled.
+ */
+export declare const assertNever: (value: never) => never;
+//# sourceMappingURL=guards.d.ts.map

package/dist/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,6CAA6C;AAC7C,eAAO,MAAM,SAAS,GAAI,CAAC,EAAE,QAAQ,CAAC,GAAG,IAAI,GAAG,SAAS,KAAG,KAAK,IAAI,CAC9B,CAAC;AAExC,6DAA6D;AAC7D,eAAO,MAAM,gBAAgB,GAAI,QAAQ,OAAO,KAAG,KAAK,IAAI,MACb,CAAC;AAEhD,8EAA8E;AAC9E,eAAO,MAAM,aAAa,GACxB,OAAO,OAAO,KACb,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAMjC,CAAC;AAEF,iEAAiE;AACjE,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,EAC1C,KAAK,OAAO,EACZ,KAAK,CAAC,KACL,GAAG,IAAI,MAAM,CAAC,CAAC,EAAE,OAAO,CAC4B,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,KAAK,KAAG,KAE1C,CAAC"}

package/dist/guards.js

@@ -0,0 +1,25 @@
+/**
+ * Type guards and assertion helpers for @ontrails/core.
+ */
+/** Narrows `T | null | undefined` to `T`. */
+export const isDefined = (value) => value !== null && value !== undefined;
+/** Returns true when `value` is a string with length > 0. */
+export const isNonEmptyString = (value) => typeof value === 'string' && value.length > 0;
+/** Returns true when `value` is a plain object (not an array, Date, etc.). */
+export const isPlainObject = (value) => {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+};
+/** Checks that `obj` is an object with the given key present. */
+export const hasProperty = (obj, key) => 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) => {
+    throw new Error(`Unexpected value: ${String(value)}`);
+};
+//# sourceMappingURL=guards.js.map

package/dist/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,6CAA6C;AAC7C,MAAM,CAAC,MAAM,SAAS,GAAG,CAAI,KAA4B,EAAc,EAAE,CACvE,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,CAAC;AAExC,6DAA6D;AAC7D,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAAe,EAAmB,EAAE,CACnE,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;AAEhD,8EAA8E;AAC9E,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,KAAc,EACoB,EAAE;IACpC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAY,CAAC;IACtD,OAAO,KAAK,KAAK,MAAM,CAAC,SAAS,IAAI,KAAK,KAAK,IAAI,CAAC;AACtD,CAAC,CAAC;AAEF,iEAAiE;AACjE,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,GAAY,EACZ,GAAM,EACqB,EAAE,CAC7B,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,IAAI,GAAG,CAAC;AAExD;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAY,EAAS,EAAE;IACjD,MAAM,IAAI,KAAK,CAAC,qBAAqB,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AACxD,CAAC,CAAC"}

package/dist/health.d.ts

@@ -0,0 +1,18 @@
+/** 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;
+}
+//# sourceMappingURL=health.d.ts.map

package/dist/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../src/health.ts"],"names":[],"mappings":"AAIA,8BAA8B;AAC9B,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;AAEhE,wCAAwC;AACxC,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,8BAA8B;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IACvD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,wBAAwB;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC"}