@oatscenter/trellis 0.100.0-rc.1

package/errors/TransferError.d.ts

@@ -0,0 +1,21 @@
+import Type, { type Static } from "typebox";
+import { TrellisError } from "./TrellisError.ts";
+export declare const TransferErrorDataSchema: Type.TObject<{
+    id: Type.TString;
+    type: Type.TLiteral<"TransferError">;
+    message: Type.TString;
+    operation: Type.TOptional<Type.TString>;
+    context: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+    traceId: Type.TOptional<Type.TString>;
+}>;
+export type TransferErrorData = Static<typeof TransferErrorDataSchema>;
+export declare class TransferError extends TrellisError<TransferErrorData> {
+    readonly name: "TransferError";
+    readonly operation?: string;
+    constructor(options: ErrorOptions & {
+        operation?: string;
+        context?: Record<string, unknown>;
+        id?: string;
+    });
+    toSerializable(): TransferErrorData;
+}

package/errors/TransferError.js

@@ -0,0 +1,31 @@
+import Type, {} from "typebox";
+import { TrellisError } from "./TrellisError.js";
+export const TransferErrorDataSchema = Type.Object({
+    id: Type.String(),
+    type: Type.Literal("TransferError"),
+    message: Type.String(),
+    operation: Type.Optional(Type.String()),
+    context: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+    traceId: Type.Optional(Type.String()),
+});
+export class TransferError extends TrellisError {
+    name = "TransferError";
+    operation;
+    constructor(options) {
+        const { operation, ...baseOptions } = options;
+        const message = `Transfer ${operation || "operation"} failed`;
+        super(message, baseOptions);
+        this.operation = operation;
+    }
+    toSerializable() {
+        const base = this.baseSerializable();
+        return {
+            id: base.id,
+            type: this.name,
+            message: base.message,
+            ...(this.operation !== undefined ? { operation: this.operation } : {}),
+            ...(base.context !== undefined ? { context: base.context } : {}),
+            ...(base.traceId !== undefined ? { traceId: base.traceId } : {}),
+        };
+    }
+}

package/errors/TransportError.d.ts

@@ -0,0 +1,29 @@
+import Type, { type Static } from "typebox";
+import { TrellisError } from "./TrellisError.ts";
+export declare const TransportErrorDataSchema: Type.TObject<{
+    id: Type.TString;
+    type: Type.TLiteral<"TransportError">;
+    message: Type.TString;
+    code: Type.TString;
+    hint: Type.TString;
+    context: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+    traceId: Type.TOptional<Type.TString>;
+}>;
+export type TransportErrorData = Static<typeof TransportErrorDataSchema>;
+/**
+ * Error for Trellis runtime transport failures.
+ */
+export declare class TransportError extends TrellisError<TransportErrorData> {
+    readonly name: "TransportError";
+    readonly code: string;
+    readonly hint: string;
+    constructor(options: ErrorOptions & {
+        code: string;
+        message: string;
+        hint: string;
+        context?: Record<string, unknown>;
+        id?: string;
+        traceId?: string;
+    });
+    toSerializable(): TransportErrorData;
+}

package/errors/TransportError.js

@@ -0,0 +1,33 @@
+import Type, {} from "typebox";
+import { TrellisError } from "./TrellisError.js";
+export const TransportErrorDataSchema = Type.Object({
+    id: Type.String(),
+    type: Type.Literal("TransportError"),
+    message: Type.String(),
+    code: Type.String(),
+    hint: Type.String(),
+    context: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+    traceId: Type.Optional(Type.String()),
+});
+/**
+ * Error for Trellis runtime transport failures.
+ */
+export class TransportError extends TrellisError {
+    name = "TransportError";
+    code;
+    hint;
+    constructor(options) {
+        const { code, message, hint, ...baseOptions } = options;
+        super(message, baseOptions);
+        this.code = code;
+        this.hint = hint;
+    }
+    toSerializable() {
+        return {
+            ...this.baseSerializable(),
+            type: this.name,
+            code: this.code,
+            hint: this.hint,
+        };
+    }
+}

package/errors/TrellisError.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Base class for all Trellis-specific errors.
+ * Extends BaseError and relies on the traceId getter being configured via initTelemetry.
+ */
+import { BaseError, type BaseErrorSchema } from "@oatscenter/result";
+/**
+ * Abstract base class for Trellis errors.
+ * Trellis errors automatically include traceId when initTelemetry() has been called
+ * and a span is active in the current context.
+ *
+ * The traceId integration is configured by the telemetry module's initTelemetry() function,
+ * which sets up BaseError.traceIdGetter to retrieve the traceId from the active span.
+ */
+export declare abstract class TrellisError<TData extends BaseErrorSchema = BaseErrorSchema> extends BaseError<TData> {
+}

package/errors/TrellisError.js

@@ -0,0 +1,15 @@
+/**
+ * Base class for all Trellis-specific errors.
+ * Extends BaseError and relies on the traceId getter being configured via initTelemetry.
+ */
+import { BaseError } from "@oatscenter/result";
+/**
+ * Abstract base class for Trellis errors.
+ * Trellis errors automatically include traceId when initTelemetry() has been called
+ * and a span is active in the current context.
+ *
+ * The traceId integration is configured by the telemetry module's initTelemetry() function,
+ * which sets up BaseError.traceIdGetter to retrieve the traceId from the active span.
+ */
+export class TrellisError extends BaseError {
+}

package/errors/ValidationError.d.ts

@@ -0,0 +1,50 @@
+import type { TLocalizedValidationError } from "typebox/error";
+import Type, { type Static } from "typebox";
+import { TrellisError } from "./TrellisError.ts";
+export type ValidationErrorInput = TLocalizedValidationError | {
+    path: string;
+    message: string;
+};
+/**
+ * Schema for validation issue in ValidationError.
+ */
+export declare const ValidationIssueSchema: Type.TObject<{
+    path: Type.TString;
+    message: Type.TString;
+}>;
+export type ValidationIssue = Static<typeof ValidationIssueSchema>;
+/**
+ * Schema for ValidationError serialization.
+ */
+export declare const ValidationErrorDataSchema: Type.TObject<{
+    id: Type.TString;
+    type: Type.TLiteral<"ValidationError">;
+    message: Type.TString;
+    issues: Type.TArray<Type.TObject<{
+        path: Type.TString;
+        message: Type.TString;
+    }>>;
+    context: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+    traceId: Type.TOptional<Type.TString>;
+}>;
+export type ValidationErrorData = Static<typeof ValidationErrorDataSchema>;
+/**
+ * Error for data validation failures.
+ * Includes schema validation and missing required data.
+ */
+export declare class ValidationError extends TrellisError<ValidationErrorData> {
+    #private;
+    readonly name: "ValidationError";
+    constructor(options: ErrorOptions & {
+        errors: Iterable<ValidationErrorInput>;
+        context?: Record<string, unknown>;
+        id?: string;
+    });
+    /**
+     * Serializes error to a plain object.
+     * Transforms internal errors array to issues array for serialization.
+     *
+     * @returns Plain object representation of the error
+     */
+    toSerializable(): ValidationErrorData;
+}

package/errors/ValidationError.js

@@ -0,0 +1,59 @@
+import Type, {} from "typebox";
+import { TrellisError } from "./TrellisError.js";
+function normalizeError(e) {
+    if ("schemaPath" in e) {
+        return { schemaPath: e.schemaPath, message: e.message ?? "Invalid value" };
+    }
+    return { schemaPath: e.path, message: e.message };
+}
+/**
+ * Schema for validation issue in ValidationError.
+ */
+export const ValidationIssueSchema = Type.Object({
+    path: Type.String(),
+    message: Type.String(),
+});
+/**
+ * Schema for ValidationError serialization.
+ */
+export const ValidationErrorDataSchema = Type.Object({
+    id: Type.String(),
+    type: Type.Literal("ValidationError"),
+    message: Type.String(),
+    issues: Type.Array(ValidationIssueSchema),
+    context: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+    traceId: Type.Optional(Type.String()),
+});
+/**
+ * Error for data validation failures.
+ * Includes schema validation and missing required data.
+ */
+export class ValidationError extends TrellisError {
+    name = "ValidationError";
+    #normalizedErrors;
+    constructor(options) {
+        const { errors: rawErrors, ...baseOptions } = options;
+        const errors = [...rawErrors].map(normalizeError);
+        const msg = errors
+            .map((e) => `Validation failed. ${e.schemaPath}: ${e.message}.`)
+            .join("\n");
+        super(msg.length ? msg : "Data validation failed.", baseOptions);
+        this.#normalizedErrors = errors;
+    }
+    /**
+     * Serializes error to a plain object.
+     * Transforms internal errors array to issues array for serialization.
+     *
+     * @returns Plain object representation of the error
+     */
+    toSerializable() {
+        return {
+            ...this.baseSerializable(),
+            type: this.name,
+            issues: this.#normalizedErrors.map((e) => ({
+                path: e.schemaPath,
+                message: e.message,
+            })),
+        };
+    }
+}

package/errors/index.d.ts

@@ -0,0 +1,254 @@
+import { UnexpectedError, type UnexpectedErrorData } from "@oatscenter/result";
+import { AuthError } from "./AuthError.ts";
+import type { AuthErrorData } from "./AuthError.ts";
+import { ValidationError } from "./ValidationError.ts";
+import type { ValidationErrorData } from "./ValidationError.ts";
+import { SchemaValidationError } from "./SchemaValidationError.ts";
+import type { SchemaValidationErrorData } from "./SchemaValidationError.ts";
+import { RemoteError } from "./RemoteError.ts";
+import { KVError } from "./KVError.ts";
+import type { KVErrorData } from "./KVError.ts";
+import { OperationAlreadyTerminalError, OperationMismatchError, OperationNotFoundError } from "./OperationLifecycleError.ts";
+import type { OperationAlreadyTerminalErrorData, OperationMismatchErrorData, OperationNotFoundErrorData } from "./OperationLifecycleError.ts";
+import { StoreError } from "./StoreError.ts";
+import type { StoreErrorData } from "./StoreError.ts";
+import { TransportError } from "./TransportError.ts";
+import type { TransportErrorData } from "./TransportError.ts";
+import { TransferError } from "./TransferError.ts";
+import type { TransferErrorData } from "./TransferError.ts";
+type RuntimeRpcErrorDesc = {
+    type: string;
+    schema?: unknown;
+    fromSerializable(data: unknown): Error;
+};
+export { UnexpectedError } from "@oatscenter/result";
+export { TrellisError } from "./TrellisError.ts";
+export { AuthError } from "./AuthError.ts";
+export { ValidationError } from "./ValidationError.ts";
+export { SchemaValidationError } from "./SchemaValidationError.ts";
+export { RemoteError } from "./RemoteError.ts";
+export { KVError } from "./KVError.ts";
+export { OperationAlreadyTerminalError, OperationMismatchError, OperationNotFoundError, } from "./OperationLifecycleError.ts";
+export { StoreError } from "./StoreError.ts";
+export { TransportError } from "./TransportError.ts";
+export { TransferError } from "./TransferError.ts";
+export { type AuthErrorData, AuthErrorDataSchema } from "./AuthError.ts";
+export { type ValidationErrorData, ValidationErrorDataSchema, type ValidationIssue, ValidationIssueSchema, } from "./ValidationError.ts";
+export { type SchemaValidationErrorData, SchemaValidationErrorDataSchema, type SchemaValidationIssue, SchemaValidationIssueSchema, } from "./SchemaValidationError.ts";
+export { type RemoteErrorData, RemoteErrorDataSchema } from "./RemoteError.ts";
+export { type KVErrorData, KVErrorDataSchema } from "./KVError.ts";
+export { type OperationAlreadyTerminalErrorData, OperationAlreadyTerminalErrorDataSchema, type OperationMismatchErrorData, OperationMismatchErrorDataSchema, type OperationNotFoundErrorData, OperationNotFoundErrorDataSchema, } from "./OperationLifecycleError.ts";
+export { type StoreErrorData, StoreErrorDataSchema } from "./StoreError.ts";
+export { type TransportErrorData, TransportErrorDataSchema, } from "./TransportError.ts";
+export { type TransferErrorData, TransferErrorDataSchema, } from "./TransferError.ts";
+/**
+ * Single source of truth for all Trellis errors.
+ * This object is used for compile-time type inference.
+ */
+declare const TRANSPORTABLE_TRELLIS_ERRORS: {
+    readonly UnexpectedError: typeof UnexpectedError;
+    readonly TransportError: typeof TransportError;
+    readonly AuthError: typeof AuthError;
+    readonly ValidationError: typeof ValidationError;
+    readonly SchemaValidationError: typeof SchemaValidationError;
+    readonly KVError: typeof KVError;
+    readonly OperationNotFoundError: typeof OperationNotFoundError;
+    readonly OperationAlreadyTerminalError: typeof OperationAlreadyTerminalError;
+    readonly OperationMismatchError: typeof OperationMismatchError;
+    readonly StoreError: typeof StoreError;
+    readonly TransferError: typeof TransferError;
+};
+declare const TRELLIS_ERRORS: {
+    readonly RemoteError: typeof RemoteError;
+    readonly UnexpectedError: typeof UnexpectedError;
+    readonly TransportError: typeof TransportError;
+    readonly AuthError: typeof AuthError;
+    readonly ValidationError: typeof ValidationError;
+    readonly SchemaValidationError: typeof SchemaValidationError;
+    readonly KVError: typeof KVError;
+    readonly OperationNotFoundError: typeof OperationNotFoundError;
+    readonly OperationAlreadyTerminalError: typeof OperationAlreadyTerminalError;
+    readonly OperationMismatchError: typeof OperationMismatchError;
+    readonly StoreError: typeof StoreError;
+    readonly TransferError: typeof TransferError;
+};
+/**
+ * Compile-time mapping from error names to their instance types.
+ * Derived from TRELLIS_ERRORS to ensure types stay in sync with runtime.
+ */
+export type TrellisErrorMap = {
+    [K in keyof typeof TRELLIS_ERRORS]: InstanceType<(typeof TRELLIS_ERRORS)[K]>;
+};
+export type TransportableTrellisErrorMap = {
+    [K in keyof typeof TRANSPORTABLE_TRELLIS_ERRORS]: InstanceType<(typeof TRANSPORTABLE_TRELLIS_ERRORS)[K]>;
+};
+export type TrellisErrorName = keyof TransportableTrellisErrorMap;
+export type TrellisErrorInstance = TrellisErrorMap[TrellisErrorName];
+export type MapErrorNamesToTypes<T extends readonly TrellisErrorName[]> = {
+    [K in keyof T]: T[K] extends TrellisErrorName ? TransportableTrellisErrorMap[T[K]] : never;
+}[number];
+export declare const BUILTIN_RPC_ERRORS: {
+    readonly UnexpectedError: {
+        readonly type: "UnexpectedError";
+        readonly schema: import("typebox").TObject<{
+            id: import("typebox").TString;
+            type: import("typebox").TLiteral<"UnexpectedError">;
+            message: import("typebox").TString;
+            context: import("typebox").TOptional<import("typebox").TRecord<"^.*$", import("typebox").TUnknown>>;
+            traceId: import("typebox").TOptional<import("typebox").TString>;
+        }>;
+        readonly fromSerializable: (data: UnexpectedErrorData) => UnexpectedError;
+    };
+    readonly AuthError: {
+        readonly type: "AuthError";
+        readonly schema: import("typebox").TObject<{
+            id: import("typebox").TString;
+            type: import("typebox").TLiteral<"AuthError">;
+            message: import("typebox").TString;
+            reason: import("typebox").TString;
+            context: import("typebox").TOptional<import("typebox").TRecord<"^.*$", import("typebox").TUnknown>>;
+            traceId: import("typebox").TOptional<import("typebox").TString>;
+        }>;
+        readonly fromSerializable: (data: AuthErrorData) => AuthError;
+    };
+    readonly TransportError: {
+        readonly type: "TransportError";
+        readonly schema: import("typebox").TObject<{
+            id: import("typebox").TString;
+            type: import("typebox").TLiteral<"TransportError">;
+            message: import("typebox").TString;
+            code: import("typebox").TString;
+            hint: import("typebox").TString;
+            context: import("typebox").TOptional<import("typebox").TRecord<"^.*$", import("typebox").TUnknown>>;
+            traceId: import("typebox").TOptional<import("typebox").TString>;
+        }>;
+        readonly fromSerializable: (data: TransportErrorData) => TransportError;
+    };
+    readonly ValidationError: {
+        readonly type: "ValidationError";
+        readonly schema: import("typebox").TObject<{
+            id: import("typebox").TString;
+            type: import("typebox").TLiteral<"ValidationError">;
+            message: import("typebox").TString;
+            issues: import("typebox").TArray<import("typebox").TObject<{
+                path: import("typebox").TString;
+                message: import("typebox").TString;
+            }>>;
+            context: import("typebox").TOptional<import("typebox").TRecord<"^.*$", import("typebox").TUnknown>>;
+            traceId: import("typebox").TOptional<import("typebox").TString>;
+        }>;
+        readonly fromSerializable: (data: ValidationErrorData) => ValidationError;
+    };
+    readonly SchemaValidationError: {
+        readonly type: "SchemaValidationError";
+        readonly schema: import("typebox").TObject<{
+            id: import("typebox").TString;
+            type: import("typebox").TLiteral<"SchemaValidationError">;
+            message: import("typebox").TString;
+            issues: import("typebox").TArray<import("typebox").TObject<{
+                path: import("typebox").TString;
+                schemaPath: import("typebox").TOptional<import("typebox").TString>;
+                keyword: import("typebox").TString;
+                code: import("typebox").TString;
+                message: import("typebox").TString;
+                label: import("typebox").TOptional<import("typebox").TString>;
+                note: import("typebox").TOptional<import("typebox").TString>;
+                i18nKey: import("typebox").TOptional<import("typebox").TString>;
+                severity: import("typebox").TOptional<import("typebox").TUnion<[import("typebox").TLiteral<"error">, import("typebox").TLiteral<"warning">, import("typebox").TLiteral<"info">]>>;
+                params: import("typebox").TOptional<import("typebox").TRecord<"^.*$", import("typebox").TUnknown>>;
+            }>>;
+            context: import("typebox").TOptional<import("typebox").TRecord<"^.*$", import("typebox").TUnknown>>;
+            traceId: import("typebox").TOptional<import("typebox").TString>;
+        }>;
+        readonly fromSerializable: (data: SchemaValidationErrorData) => SchemaValidationError;
+    };
+    readonly KVError: {
+        readonly type: "KVError";
+        readonly schema: import("typebox").TObject<{
+            id: import("typebox").TString;
+            type: import("typebox").TLiteral<"KVError">;
+            message: import("typebox").TString;
+            operation: import("typebox").TOptional<import("typebox").TString>;
+            context: import("typebox").TOptional<import("typebox").TRecord<"^.*$", import("typebox").TUnknown>>;
+            traceId: import("typebox").TOptional<import("typebox").TString>;
+        }>;
+        readonly fromSerializable: (data: KVErrorData) => KVError;
+    };
+    readonly OperationNotFoundError: {
+        readonly type: "OperationNotFoundError";
+        readonly schema: import("typebox").TObject<{
+            id: import("typebox").TString;
+            type: import("typebox").TLiteral<"OperationNotFoundError">;
+            message: import("typebox").TString;
+            operationId: import("typebox").TString;
+            context: import("typebox").TOptional<import("typebox").TRecord<"^.*$", import("typebox").TUnknown>>;
+            traceId: import("typebox").TOptional<import("typebox").TString>;
+        }>;
+        readonly fromSerializable: (data: OperationNotFoundErrorData) => OperationNotFoundError;
+    };
+    readonly OperationAlreadyTerminalError: {
+        readonly type: "OperationAlreadyTerminalError";
+        readonly schema: import("typebox").TObject<{
+            id: import("typebox").TString;
+            type: import("typebox").TLiteral<"OperationAlreadyTerminalError">;
+            message: import("typebox").TString;
+            operationId: import("typebox").TString;
+            state: import("typebox").TOptional<import("typebox").TString>;
+            operation: import("typebox").TOptional<import("typebox").TString>;
+            service: import("typebox").TOptional<import("typebox").TString>;
+            context: import("typebox").TOptional<import("typebox").TRecord<"^.*$", import("typebox").TUnknown>>;
+            traceId: import("typebox").TOptional<import("typebox").TString>;
+        }>;
+        readonly fromSerializable: (data: OperationAlreadyTerminalErrorData) => OperationAlreadyTerminalError;
+    };
+    readonly OperationMismatchError: {
+        readonly type: "OperationMismatchError";
+        readonly schema: import("typebox").TObject<{
+            id: import("typebox").TString;
+            type: import("typebox").TLiteral<"OperationMismatchError">;
+            message: import("typebox").TString;
+            operationId: import("typebox").TString;
+            expectedService: import("typebox").TString;
+            expectedOperation: import("typebox").TString;
+            actualService: import("typebox").TOptional<import("typebox").TString>;
+            actualOperation: import("typebox").TOptional<import("typebox").TString>;
+            context: import("typebox").TOptional<import("typebox").TRecord<"^.*$", import("typebox").TUnknown>>;
+            traceId: import("typebox").TOptional<import("typebox").TString>;
+        }>;
+        readonly fromSerializable: (data: OperationMismatchErrorData) => OperationMismatchError;
+    };
+    readonly StoreError: {
+        readonly type: "StoreError";
+        readonly schema: import("typebox").TObject<{
+            id: import("typebox").TString;
+            type: import("typebox").TLiteral<"StoreError">;
+            message: import("typebox").TString;
+            operation: import("typebox").TOptional<import("typebox").TString>;
+            context: import("typebox").TOptional<import("typebox").TRecord<"^.*$", import("typebox").TUnknown>>;
+            traceId: import("typebox").TOptional<import("typebox").TString>;
+        }>;
+        readonly fromSerializable: (data: StoreErrorData) => StoreError;
+    };
+    readonly TransferError: {
+        readonly type: "TransferError";
+        readonly schema: import("typebox").TObject<{
+            id: import("typebox").TString;
+            type: import("typebox").TLiteral<"TransferError">;
+            message: import("typebox").TString;
+            operation: import("typebox").TOptional<import("typebox").TString>;
+            context: import("typebox").TOptional<import("typebox").TRecord<"^.*$", import("typebox").TUnknown>>;
+            traceId: import("typebox").TOptional<import("typebox").TString>;
+        }>;
+        readonly fromSerializable: (data: TransferErrorData) => TransferError;
+    };
+};
+export declare function getBuiltinRpcError(type: string): RuntimeRpcErrorDesc | undefined;
+/**
+ * Reads the machine-readable failure code from any Trellis error shape.
+ *
+ * Declared RPC errors reconstruct into generated error classes that carry the
+ * code under `data`, built-in errors carry `reason`, and undecoded remote
+ * failures carry it under `remoteError`. Callers that must branch on a specific
+ * server code use this instead of matching one historical shape.
+ */
+export declare function machineErrorCode(error: unknown): string | undefined;