@daihum/error-state 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# @daihum/error-state
+
+Neutral typed error-state mechanism for DAIHUM and downstream hosts.
+
+This package owns the runtime-free mechanism:
+
+- the frozen `carrel.runtime.error.v0` envelope;
+- local `const` error-kind declarations through `defineErrorKinds`;
+- `ErrorStateOf<typeof kinds>` type derivation;
+- a registry contribution port;
+- an injected schema validation port for typed `details`.
+
+It deliberately does not own product feature declarations, registry storage,
+documentation generation, Carrel migration, or schema-library choice.
+
+```ts
+import { defineErrorKinds, type SchemaPort } from "@daihum/error-state";
+
+interface MissingDocumentDetails {
+  readonly fileUri: string;
+}
+
+const missingDocumentDetails: SchemaPort<MissingDocumentDetails> = {
+  validate(value) {
+    if (
+      typeof value === "object" &&
+      value !== null &&
+      typeof (value as { fileUri?: unknown }).fileUri === "string"
+    ) {
+      return { ok: true, value: { fileUri: (value as { fileUri: string }).fileUri } };
+    }
+    return { ok: false, error: { message: "fileUri is required" } };
+  },
+};
+
+export const readerErrors = defineErrorKinds("reader.pdf", {
+  missingDocument: {
+    retryable: false,
+    reason: "missing-document",
+    message: "The PDF document is not available.",
+    details: missingDocumentDetails,
+  },
+} as const);
+
+const state = readerErrors.fail("missingDocument", {
+  commandId: "reader.open",
+  details: { fileUri: "file:///paper.pdf" },
+});
+```
+
+The returned state uses the same frozen wire schema:
+
+```ts
+state.schema === "carrel.runtime.error.v0";
+```
+
+No runtime dependencies are used.

package/dist/index.d.ts

@@ -0,0 +1,93 @@
+export declare const ERROR_STATE_SCHEMA_V0: "carrel.runtime.error.v0";
+export interface ErrorStateV0<Tag extends string = string, Details = unknown> {
+    readonly schema: typeof ERROR_STATE_SCHEMA_V0;
+    readonly tag: Tag;
+    readonly retryable: boolean;
+    readonly reason?: string;
+    readonly message?: string;
+    readonly commandId?: string;
+    readonly runId?: string;
+    readonly stepId?: string;
+    readonly correlationId?: string;
+    readonly details?: Details;
+}
+export interface SchemaPortErrorV0 {
+    readonly message?: string;
+    readonly issues?: readonly unknown[];
+    readonly cause?: unknown;
+}
+export type SchemaPortResultV0<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: SchemaPortErrorV0;
+};
+export interface SchemaPort<T> {
+    validate(value: unknown): SchemaPortResultV0<T>;
+}
+export interface ErrorKindSpecV0<Details = never> {
+    readonly retryable: boolean;
+    readonly reason?: string;
+    readonly message?: string;
+    readonly details?: SchemaPort<Details>;
+}
+export interface ErrorKindDefinitionV0<Tag extends string = string, Details = never, Retryable extends boolean = boolean> {
+    readonly tag: Tag;
+    readonly retryable: Retryable;
+    readonly reason?: string;
+    readonly message?: string;
+    readonly details?: SchemaPort<Details>;
+}
+export type ErrorKindSpecMapV0 = Readonly<Record<string, ErrorKindSpecV0<unknown>>>;
+export type ErrorKindDefinitionsV0 = Readonly<Record<string, ErrorKindDefinitionV0<string, unknown, boolean>>>;
+export interface ErrorKindRegistryPortV0<Definitions extends ErrorKindDefinitionsV0 = ErrorKindDefinitionsV0> {
+    register(namespace: string, spec: Definitions): void | Promise<void>;
+    lookup(tag: string): ErrorKindDefinitionV0 | undefined | Promise<ErrorKindDefinitionV0 | undefined>;
+}
+export type ErrorKindDetailsOf<Spec> = Spec extends {
+    readonly details: SchemaPort<infer Details>;
+} ? Details : never;
+export type ErrorKindRetryableOf<Spec> = Spec extends {
+    readonly retryable: infer Retryable extends boolean;
+} ? Retryable : boolean;
+export type ErrorKindTag<Namespace extends string, Key extends string> = `${Namespace}.${Key}`;
+export type ErrorKindDefinitionsFor<Namespace extends string, Spec extends ErrorKindSpecMapV0> = Readonly<{
+    [Key in keyof Spec & string]: ErrorKindDefinitionV0<ErrorKindTag<Namespace, Key>, ErrorKindDetailsOf<Spec[Key]>, ErrorKindRetryableOf<Spec[Key]>>;
+}>;
+export type ErrorStateForKind<Namespace extends string, Key extends string, Spec> = ErrorStateV0<ErrorKindTag<Namespace, Key>, ErrorKindDetailsOf<Spec>> & {
+    readonly retryable: ErrorKindRetryableOf<Spec>;
+};
+export type ErrorStateOf<Kinds extends ErrorKindDefinitionsV0> = {
+    [Key in keyof Kinds]: Kinds[Key] extends ErrorKindDefinitionV0<infer Tag, infer Details, infer Retryable> ? ErrorStateV0<Tag, Details> & {
+        readonly retryable: Retryable;
+    } : never;
+}[keyof Kinds];
+export type ErrorStateFailInputV0<Details = never> = {
+    readonly reason?: string;
+    readonly message?: string;
+    readonly commandId?: string;
+    readonly runId?: string;
+    readonly stepId?: string;
+    readonly correlationId?: string;
+} & ([Details] extends [never] ? {
+    readonly details?: never;
+} : {
+    readonly details?: Details;
+});
+export type ErrorStateBuildResultV0<State extends ErrorStateV0> = {
+    readonly ok: true;
+    readonly value: State;
+} | {
+    readonly ok: false;
+    readonly error: SchemaPortErrorV0;
+    readonly state: State;
+};
+export interface DefinedErrorKindsV0<Namespace extends string, Spec extends ErrorKindSpecMapV0> {
+    readonly namespace: Namespace;
+    readonly kinds: ErrorKindDefinitionsFor<Namespace, Spec>;
+    fail<Key extends keyof Spec & string>(tag: Key, input?: ErrorStateFailInputV0<ErrorKindDetailsOf<Spec[Key]>>): ErrorStateForKind<Namespace, Key, Spec[Key]>;
+    tryFail<Key extends keyof Spec & string>(tag: Key, input?: ErrorStateFailInputV0<ErrorKindDetailsOf<Spec[Key]>>): ErrorStateBuildResultV0<ErrorStateForKind<Namespace, Key, Spec[Key]>>;
+    contribute(registry: ErrorKindRegistryPortV0<ErrorKindDefinitionsFor<Namespace, Spec>>): void | Promise<void>;
+}
+export declare function defineErrorKinds<const Namespace extends string, const Spec extends ErrorKindSpecMapV0>(namespace: Namespace, constSpec: Spec): DefinedErrorKindsV0<Namespace, Spec>;

package/dist/index.js

@@ -0,0 +1,63 @@
+export const ERROR_STATE_SCHEMA_V0 = "carrel.runtime.error.v0";
+function buildInvalidDetailsMessage(tag, error) {
+    return error.message ?? `Invalid error-state details for ${tag}.`;
+}
+function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+export function defineErrorKinds(namespace, constSpec) {
+    const kinds = Object.freeze(Object.fromEntries(Object.entries(constSpec).map(([key, spec]) => [
+        key,
+        Object.freeze({
+            tag: `${namespace}.${key}`,
+            retryable: spec.retryable,
+            ...(spec.reason !== undefined ? { reason: spec.reason } : {}),
+            ...(spec.message !== undefined ? { message: spec.message } : {}),
+            ...(spec.details !== undefined ? { details: spec.details } : {}),
+        }),
+    ])));
+    function tryFail(key, input = {}) {
+        const kind = kinds[key];
+        const reason = input.reason ?? kind.reason;
+        const message = input.message ?? kind.message;
+        const stateBase = {
+            schema: ERROR_STATE_SCHEMA_V0,
+            tag: kind.tag,
+            retryable: kind.retryable,
+            ...(reason !== undefined ? { reason } : {}),
+            ...(message !== undefined ? { message } : {}),
+            ...(input.commandId !== undefined ? { commandId: input.commandId } : {}),
+            ...(input.runId !== undefined ? { runId: input.runId } : {}),
+            ...(input.stepId !== undefined ? { stepId: input.stepId } : {}),
+            ...(input.correlationId !== undefined ? { correlationId: input.correlationId } : {}),
+        };
+        if (!hasOwn(input, "details"))
+            return { ok: true, value: stateBase };
+        const rawDetails = input.details;
+        if (kind.details !== undefined) {
+            const result = kind.details.validate(rawDetails);
+            if (!result.ok) {
+                const state = {
+                    ...stateBase,
+                    reason: "invalid-error-details",
+                    message: buildInvalidDetailsMessage(kind.tag, result.error),
+                };
+                return { ok: false, error: result.error, state };
+            }
+            return { ok: true, value: { ...stateBase, details: result.value } };
+        }
+        return { ok: true, value: { ...stateBase, details: rawDetails } };
+    }
+    return Object.freeze({
+        namespace,
+        kinds,
+        fail(key, input) {
+            const result = tryFail(key, input);
+            return result.ok ? result.value : result.state;
+        },
+        tryFail,
+        contribute(registry) {
+            return registry.register(namespace, kinds);
+        },
+    });
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@daihum/error-state",
+  "version": "0.1.0",
+  "description": "Neutral typed error-state mechanism: frozen carrel.runtime.error.v0 envelope, const-spec kind definitions, registry contribution port, and injected details validation. Runtime-free and zero dependency.",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "daihum",
+    "error-state",
+    "typed-errors",
+    "runtime-contract"
+  ],
+  "author": "DAIHUM",
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "~5.6.2",
+    "vitest": "^2.1.8"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}