@cullet/erp-core 1.5.0 → 2.0.0

package/dist/requested-by.js.map

@@ -1 +1 @@
-{"version":3,"file":"requested-by.js","names":[],"sources":["../src/core/application/commands/requested-by.ts"],"sourcesContent":["import { ValidationCode } from \"../../exceptions/validation-code.js\";\nimport { InvalidValueException } from \"../../exceptions/validation-exception.js\";\nimport { ValidationField } from \"../../exceptions/validation-field.js\";\nimport { UUID_PATTERN } from \"../../shared/uuid.js\";\n\n// Identifies who triggered a Command.\n// Two valid formats:\n//   - Human user: canonical RFC-4122 UUID, versions 1–5 — the same pattern\n//     `UuidIdentifier` enforces (e.g.: \"550e8400-e29b-41d4-a716-446655440000\")\n//   - System identity: \"system:<job>\" where <job> is [a-z][a-z0-9]*(-[a-z0-9]+)*\n//     (e.g.: \"system:late-fee-job\", \"system:email-sender\")\n//\n// The split between `fromUser` / `fromSystem` / `parse` exists to make intent\n// explicit at the call-site: whoever builds the value knows where it came from.\n\ntype RequestedByKind = \"user\" | \"system\";\n\nconst REQUESTED_BY_FIELD = ValidationField.of(\"requestedBy\");\n\n// system:<job> where <job> starts with a lowercase letter and may have hyphens between segments\nconst SYSTEM_IDENTITY_PATTERN = /^system:[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;\n\nclass RequestedBy {\n    readonly kind: RequestedByKind;\n    readonly raw: string;\n\n    private constructor(kind: RequestedByKind, raw: string) {\n        this.kind = kind;\n        this.raw = raw;\n        Object.freeze(this);\n    }\n\n    /** Builds from a human user ID (must be a UUID). */\n    static fromUser(userId: string): RequestedBy {\n        if (!UUID_PATTERN.test(userId)) {\n            throw new InvalidValueException(\n                REQUESTED_BY_FIELD,\n                ValidationCode.INVALID_FORMAT,\n                `requestedBy: user identity must be a UUID, got \"${userId}\"`,\n            );\n        }\n\n        return new RequestedBy(\"user\", userId);\n    }\n\n    /**\n     * Builds from a system identity.\n     * Only accepts the format \"system:<job>\", where <job> matches [a-z][a-z0-9]*(-[a-z0-9]+)*.\n     */\n    static fromSystem(systemIdentity: string): RequestedBy {\n        if (!SYSTEM_IDENTITY_PATTERN.test(systemIdentity)) {\n            throw new InvalidValueException(\n                REQUESTED_BY_FIELD,\n                ValidationCode.INVALID_FORMAT,\n                `requestedBy: system identity must match \"system:<job>\" (e.g. \"system:late-fee-job\"), got \"${systemIdentity}\"`,\n            );\n        }\n\n        return new RequestedBy(\"system\", systemIdentity);\n    }\n\n    /**\n     * Infers the kind from the raw value.\n     * Use when the origin (user vs system) is not known at the call-site.\n     */\n    static parse(raw: string): RequestedBy {\n        if (UUID_PATTERN.test(raw)) {\n            return new RequestedBy(\"user\", raw);\n        }\n\n        if (SYSTEM_IDENTITY_PATTERN.test(raw)) {\n            return new RequestedBy(\"system\", raw);\n        }\n\n        throw new InvalidValueException(\n            REQUESTED_BY_FIELD,\n            ValidationCode.INVALID_FORMAT,\n            `requestedBy must be a UUID (user) or \"system:<job>\" (system), got \"${raw}\"`,\n        );\n    }\n\n    get isUser(): boolean {\n        return this.kind === \"user\";\n    }\n\n    get isSystem(): boolean {\n        return this.kind === \"system\";\n    }\n\n    toString(): string {\n        return this.raw;\n    }\n}\n\nexport type { RequestedByKind };\nexport { RequestedBy };\n"],"mappings":";;;;;AAiBA,MAAM,qBAAqB,gBAAgB,GAAG,aAAa;AAG3D,MAAM,0BAA0B;AAEhC,IAAM,cAAN,MAAM,YAAY;CAId,YAAoB,MAAuB,KAAa;EACpD,KAAK,OAAO;EACZ,KAAK,MAAM;EACX,OAAO,OAAO,IAAI;CACtB;;CAGA,OAAO,SAAS,QAA6B;EACzC,IAAI,CAAC,aAAa,KAAK,MAAM,GACzB,MAAM,IAAI,sBACN,oBACA,eAAe,gBACf,mDAAmD,OAAO,EAC9D;EAGJ,OAAO,IAAI,YAAY,QAAQ,MAAM;CACzC;;;;;CAMA,OAAO,WAAW,gBAAqC;EACnD,IAAI,CAAC,wBAAwB,KAAK,cAAc,GAC5C,MAAM,IAAI,sBACN,oBACA,eAAe,gBACf,6FAA6F,eAAe,EAChH;EAGJ,OAAO,IAAI,YAAY,UAAU,cAAc;CACnD;;;;;CAMA,OAAO,MAAM,KAA0B;EACnC,IAAI,aAAa,KAAK,GAAG,GACrB,OAAO,IAAI,YAAY,QAAQ,GAAG;EAGtC,IAAI,wBAAwB,KAAK,GAAG,GAChC,OAAO,IAAI,YAAY,UAAU,GAAG;EAGxC,MAAM,IAAI,sBACN,oBACA,eAAe,gBACf,sEAAsE,IAAI,EAC9E;CACJ;CAEA,IAAI,SAAkB;EAClB,OAAO,KAAK,SAAS;CACzB;CAEA,IAAI,WAAoB;EACpB,OAAO,KAAK,SAAS;CACzB;CAEA,WAAmB;EACf,OAAO,KAAK;CAChB;AACJ"}
+{"version":3,"file":"requested-by.js","names":[],"sources":["../src/core/application/commands/requested-by.ts"],"sourcesContent":["import { ValidationCode } from \"../../exceptions/validation-code.js\";\nimport { InvalidValueException } from \"../../exceptions/validation-exception.js\";\nimport { ValidationField } from \"../../exceptions/validation-field.js\";\nimport { UUID_PATTERN } from \"../../shared/uuid.js\";\n\n// Identifies who triggered a Command.\n// Two valid formats:\n//   - Human user: canonical RFC-4122 UUID, versions 1–8 (including the\n//     time-ordered v7) — the same pattern `UuidIdentifier` enforces\n//     (e.g.: \"550e8400-e29b-41d4-a716-446655440000\"). The constraint is\n//     single-sourced in `shared/uuid.ts`, so `UuidIdentifier` and this value\n//     always accept the same set of versions.\n//   - System identity: \"system:<job>\" where <job> is [a-z][a-z0-9]*(-[a-z0-9]+)*\n//     (e.g.: \"system:late-fee-job\", \"system:email-sender\")\n//\n// The split between `fromUser` / `fromSystem` / `parse` exists to make intent\n// explicit at the call-site: whoever builds the value knows where it came from.\n\ntype RequestedByKind = \"user\" | \"system\";\n\nconst REQUESTED_BY_FIELD = ValidationField.of(\"requestedBy\");\n\n// system:<job> where <job> starts with a lowercase letter and may have hyphens between segments\nconst SYSTEM_IDENTITY_PATTERN = /^system:[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;\n\nclass RequestedBy {\n    readonly kind: RequestedByKind;\n    readonly raw: string;\n\n    private constructor(kind: RequestedByKind, raw: string) {\n        this.kind = kind;\n        // UUIDs are matched case-insensitively (see `shared/uuid.ts`), so the\n        // same user id can arrive lowercased from Postgres and uppercased from a\n        // JWT. Canonicalize user ids to lowercase here — the single choke point\n        // every factory passes through — so exact-string comparators downstream\n        // (`Grant.appliesTo`, `rbacContextFields`) never miss the right identity\n        // on case alone. System identities are already lowercase by pattern.\n        this.raw = kind === \"user\" ? raw.toLowerCase() : raw;\n        Object.freeze(this);\n    }\n\n    /** Builds from a human user ID (must be a UUID). */\n    static fromUser(userId: string): RequestedBy {\n        if (!UUID_PATTERN.test(userId)) {\n            throw new InvalidValueException(\n                REQUESTED_BY_FIELD,\n                ValidationCode.INVALID_FORMAT,\n                `requestedBy: user identity must be a UUID, got \"${userId}\"`,\n            );\n        }\n\n        return new RequestedBy(\"user\", userId);\n    }\n\n    /**\n     * Builds from a system identity.\n     * Only accepts the format \"system:<job>\", where <job> matches [a-z][a-z0-9]*(-[a-z0-9]+)*.\n     */\n    static fromSystem(systemIdentity: string): RequestedBy {\n        if (!SYSTEM_IDENTITY_PATTERN.test(systemIdentity)) {\n            throw new InvalidValueException(\n                REQUESTED_BY_FIELD,\n                ValidationCode.INVALID_FORMAT,\n                `requestedBy: system identity must match \"system:<job>\" (e.g. \"system:late-fee-job\"), got \"${systemIdentity}\"`,\n            );\n        }\n\n        return new RequestedBy(\"system\", systemIdentity);\n    }\n\n    /**\n     * Infers the kind from the raw value.\n     * Use when the origin (user vs system) is not known at the call-site.\n     */\n    static parse(raw: string): RequestedBy {\n        if (UUID_PATTERN.test(raw)) {\n            return new RequestedBy(\"user\", raw);\n        }\n\n        if (SYSTEM_IDENTITY_PATTERN.test(raw)) {\n            return new RequestedBy(\"system\", raw);\n        }\n\n        throw new InvalidValueException(\n            REQUESTED_BY_FIELD,\n            ValidationCode.INVALID_FORMAT,\n            `requestedBy must be a UUID (user) or \"system:<job>\" (system), got \"${raw}\"`,\n        );\n    }\n\n    get isUser(): boolean {\n        return this.kind === \"user\";\n    }\n\n    get isSystem(): boolean {\n        return this.kind === \"system\";\n    }\n\n    toString(): string {\n        return this.raw;\n    }\n}\n\nexport type { RequestedByKind };\nexport { RequestedBy };\n"],"mappings":";;;;;AAoBA,MAAM,qBAAqB,gBAAgB,GAAG,aAAa;AAG3D,MAAM,0BAA0B;AAEhC,IAAM,cAAN,MAAM,YAAY;CAId,YAAoB,MAAuB,KAAa;EACpD,KAAK,OAAO;EAOZ,KAAK,MAAM,SAAS,SAAS,IAAI,YAAY,IAAI;EACjD,OAAO,OAAO,IAAI;CACtB;;CAGA,OAAO,SAAS,QAA6B;EACzC,IAAI,CAAC,aAAa,KAAK,MAAM,GACzB,MAAM,IAAI,sBACN,oBACA,eAAe,gBACf,mDAAmD,OAAO,EAC9D;EAGJ,OAAO,IAAI,YAAY,QAAQ,MAAM;CACzC;;;;;CAMA,OAAO,WAAW,gBAAqC;EACnD,IAAI,CAAC,wBAAwB,KAAK,cAAc,GAC5C,MAAM,IAAI,sBACN,oBACA,eAAe,gBACf,6FAA6F,eAAe,EAChH;EAGJ,OAAO,IAAI,YAAY,UAAU,cAAc;CACnD;;;;;CAMA,OAAO,MAAM,KAA0B;EACnC,IAAI,aAAa,KAAK,GAAG,GACrB,OAAO,IAAI,YAAY,QAAQ,GAAG;EAGtC,IAAI,wBAAwB,KAAK,GAAG,GAChC,OAAO,IAAI,YAAY,UAAU,GAAG;EAGxC,MAAM,IAAI,sBACN,oBACA,eAAe,gBACf,sEAAsE,IAAI,EAC9E;CACJ;CAEA,IAAI,SAAkB;EAClB,OAAO,KAAK,SAAS;CACzB;CAEA,IAAI,WAAoB;EACpB,OAAO,KAAK,SAAS;CACzB;CAEA,WAAmB;EACf,OAAO,KAAK;CAChB;AACJ"}

package/dist/result.cjs

@@ -19,6 +19,9 @@ var Result = class Result {
 	}
 	/**
 	* Returns the value when this is success, or null when this is an error.
+	*
+	* Note: an `Ok(null)` also returns `null`, indistinguishable from an `Err`.
+	* Use `match`/`isOk` when that distinction matters.
 	*/
 	getOrNull() {
 		return this.match({
@@ -42,12 +45,14 @@ var Result = class Result {
 		return this.match({
 			ok: (value) => value,
 			err: (error) => {
-				throw error instanceof Error ? error : new Error(String(error));
+				throw toError(error);
 			}
 		});
 	}
 	/**
 	* Transforms the success value using the provided function. Keeps the error when this is a failure.
+	*
+	* Exceptions thrown by `transform` propagate; they are not captured into an `Err`.
 	*/
 	map(transform) {
 		return this.match({
@@ -57,6 +62,8 @@ var Result = class Result {
 	}
 	/**
 	* Transforms the error using the provided function. Keeps the value when this is a success.
+	*
+	* Exceptions thrown by `transform` propagate; they are not captured into an `Err`.
 	*/
 	mapError(transform) {
 		return this.match({
@@ -66,6 +73,8 @@ var Result = class Result {
 	}
 	/**
 	* Chains another operation that returns a Result when this result is a success.
+	*
+	* Exceptions thrown by `transform` propagate; they are not captured into an `Err`.
 	*/
 	flatMap(transform) {
 		return this.match({
@@ -76,6 +85,9 @@ var Result = class Result {
 };
 /**
 * Success variant of Result.
+*
+* The instance is frozen, but the freeze is shallow: a contained mutable
+* object is not frozen.
 */
 var Ok = class extends Result {
 	constructor(value) {
@@ -112,6 +124,22 @@ var Err = class extends Result {
 		return handlers.err(this.error);
 	}
 };
+/**
+* Coerces an arbitrary error value into an Error for `getOrThrow`, preserving
+* the original structured payload as `cause` so nothing is lost when `E` is a
+* plain object/DTO rather than an Error.
+*/
+function toError(error) {
+	if (error instanceof Error) return error;
+	if (typeof error === "string") return new Error(error);
+	let message;
+	try {
+		message = JSON.stringify(error);
+	} catch {}
+	const wrapped = new Error(message ?? String(error));
+	wrapped.cause = error;
+	return wrapped;
+}
 //#endregion
 Object.defineProperty(exports, "Err", {
 	enumerable: true,

package/dist/result.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"result.cjs","names":[],"sources":["../src/core/result/result.ts"],"sourcesContent":["/**\n * Represents the outcome of an operation that may succeed or fail.\n * Useful for avoiding excessive exceptions and making error flows explicit.\n */\nexport abstract class Result<T, E> {\n    protected constructor() {\n        // prevent direct instantiation\n    }\n\n    /**\n     * Creates a success result containing a value.\n     */\n    static ok<T>(value: T): Result<T, never> {\n        return new Ok(value);\n    }\n\n    /**\n     * Creates an error result containing an error object.\n     */\n    static err<E>(error: E): Result<never, E> {\n        return new Err(error);\n    }\n\n    /**\n     * Returns true when this is a success result.\n     */\n    abstract isOk(): this is Ok<T>;\n\n    /**\n     * Returns true when this is an error result.\n     */\n    abstract isErr(): this is Err<E>;\n\n    /**\n     * Runs a handler based on the result state (similar to pattern matching).\n     */\n    abstract match<R>(handlers: {\n        ok: (value: T) => R;\n        err: (error: E) => R;\n    }): R;\n\n    /**\n     * Returns the value when this is success, or null when this is an error.\n     */\n    getOrNull(): T | null {\n        return this.match({\n            ok: (value) => value,\n            err: () => null,\n        });\n    }\n\n    /**\n     * Returns the error when this is a failure, or null when this is a success.\n     */\n    errorOrNull(): E | null {\n        return this.match({\n            ok: () => null,\n            err: (error) => error,\n        });\n    }\n\n    /**\n     * Returns the value when this is a success, or throws the error when this is a failure.\n     */\n    getOrThrow(): T {\n        return this.match({\n            ok: (value) => value,\n            err: (error) => {\n                throw error instanceof Error ? error : new Error(String(error));\n            },\n        });\n    }\n\n    /**\n     * Transforms the success value using the provided function. Keeps the error when this is a failure.\n     */\n    map<R>(transform: (value: T) => R): Result<R, E> {\n        return this.match<Result<R, E>>({\n            ok: (value) => Result.ok(transform(value)),\n            // TS does not \"see\" variance here; the cast is intentional and safe:\n            // Err carries no T, so it can be widened to Result<R, E> safely.\n            err: (error) => Result.err(error) as unknown as Result<R, E>,\n        });\n    }\n\n    /**\n     * Transforms the error using the provided function. Keeps the value when this is a success.\n     */\n    mapError<F>(transform: (error: E) => F): Result<T, F> {\n        return this.match<Result<T, F>>({\n            // Ok carries no E, so it can be widened to Result<T, F>.\n            ok: (value) => Result.ok(value) as unknown as Result<T, F>,\n            err: (error) => Result.err(transform(error)),\n        });\n    }\n\n    /**\n     * Chains another operation that returns a Result when this result is a success.\n     */\n    flatMap<R>(transform: (value: T) => Result<R, E>): Result<R, E> {\n        return this.match<Result<R, E>>({\n            ok: (value) => transform(value),\n            err: (error) => Result.err(error) as unknown as Result<R, E>,\n        });\n    }\n}\n\n/**\n * Success variant of Result.\n */\nexport class Ok<T> extends Result<T, never> {\n    public readonly value: T;\n\n    constructor(value: T) {\n        super();\n        this.value = value;\n        Object.freeze(this);\n    }\n\n    isOk(): this is Ok<T> {\n        return true;\n    }\n\n    isErr(): this is Err<never> {\n        return false;\n    }\n\n    match<R>(handlers: { ok: (value: T) => R; err: (error: never) => R }): R {\n        return handlers.ok(this.value);\n    }\n}\n\n/**\n * Error variant of Result.\n */\nexport class Err<E> extends Result<never, E> {\n    public readonly error: E;\n\n    constructor(error: E) {\n        super();\n        this.error = error;\n        Object.freeze(this);\n    }\n\n    isOk(): this is Ok<never> {\n        return false;\n    }\n\n    isErr(): this is Err<E> {\n        return true;\n    }\n\n    match<R>(handlers: { ok: (value: never) => R; err: (error: E) => R }): R {\n        return handlers.err(this.error);\n    }\n}\n"],"mappings":";;;;;AAIA,IAAsB,SAAtB,MAAsB,OAAa;CAC/B,cAAwB,CAExB;;;;CAKA,OAAO,GAAM,OAA4B;EACrC,OAAO,IAAI,GAAG,KAAK;CACvB;;;;CAKA,OAAO,IAAO,OAA4B;EACtC,OAAO,IAAI,IAAI,KAAK;CACxB;;;;CAuBA,YAAsB;EAClB,OAAO,KAAK,MAAM;GACd,KAAK,UAAU;GACf,WAAW;EACf,CAAC;CACL;;;;CAKA,cAAwB;EACpB,OAAO,KAAK,MAAM;GACd,UAAU;GACV,MAAM,UAAU;EACpB,CAAC;CACL;;;;CAKA,aAAgB;EACZ,OAAO,KAAK,MAAM;GACd,KAAK,UAAU;GACf,MAAM,UAAU;IACZ,MAAM,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;GAClE;EACJ,CAAC;CACL;;;;CAKA,IAAO,WAA0C;EAC7C,OAAO,KAAK,MAAoB;GAC5B,KAAK,UAAU,OAAO,GAAG,UAAU,KAAK,CAAC;GAGzC,MAAM,UAAU,OAAO,IAAI,KAAK;EACpC,CAAC;CACL;;;;CAKA,SAAY,WAA0C;EAClD,OAAO,KAAK,MAAoB;GAE5B,KAAK,UAAU,OAAO,GAAG,KAAK;GAC9B,MAAM,UAAU,OAAO,IAAI,UAAU,KAAK,CAAC;EAC/C,CAAC;CACL;;;;CAKA,QAAW,WAAqD;EAC5D,OAAO,KAAK,MAAoB;GAC5B,KAAK,UAAU,UAAU,KAAK;GAC9B,MAAM,UAAU,OAAO,IAAI,KAAK;EACpC,CAAC;CACL;AACJ;;;;AAKA,IAAa,KAAb,cAA2B,OAAiB;CAGxC,YAAY,OAAU;EAClB,MAAM;EACN,KAAK,QAAQ;EACb,OAAO,OAAO,IAAI;CACtB;CAEA,OAAsB;EAClB,OAAO;CACX;CAEA,QAA4B;EACxB,OAAO;CACX;CAEA,MAAS,UAAgE;EACrE,OAAO,SAAS,GAAG,KAAK,KAAK;CACjC;AACJ;;;;AAKA,IAAa,MAAb,cAA4B,OAAiB;CAGzC,YAAY,OAAU;EAClB,MAAM;EACN,KAAK,QAAQ;EACb,OAAO,OAAO,IAAI;CACtB;CAEA,OAA0B;EACtB,OAAO;CACX;CAEA,QAAwB;EACpB,OAAO;CACX;CAEA,MAAS,UAAgE;EACrE,OAAO,SAAS,IAAI,KAAK,KAAK;CAClC;AACJ"}
+{"version":3,"file":"result.cjs","names":[],"sources":["../src/core/result/result.ts"],"sourcesContent":["/**\n * Represents the outcome of an operation that may succeed or fail.\n * Useful for avoiding excessive exceptions and making error flows explicit.\n */\nexport abstract class Result<T, E> {\n    protected constructor() {\n        // prevent direct instantiation\n    }\n\n    /**\n     * Creates a success result containing a value.\n     */\n    static ok<T>(value: T): Result<T, never> {\n        return new Ok(value);\n    }\n\n    /**\n     * Creates an error result containing an error object.\n     */\n    static err<E>(error: E): Result<never, E> {\n        return new Err(error);\n    }\n\n    /**\n     * Returns true when this is a success result.\n     */\n    abstract isOk(): this is Ok<T>;\n\n    /**\n     * Returns true when this is an error result.\n     */\n    abstract isErr(): this is Err<E>;\n\n    /**\n     * Runs a handler based on the result state (similar to pattern matching).\n     */\n    abstract match<R>(handlers: {\n        ok: (value: T) => R;\n        err: (error: E) => R;\n    }): R;\n\n    /**\n     * Returns the value when this is success, or null when this is an error.\n     *\n     * Note: an `Ok(null)` also returns `null`, indistinguishable from an `Err`.\n     * Use `match`/`isOk` when that distinction matters.\n     */\n    getOrNull(): T | null {\n        return this.match({\n            ok: (value) => value,\n            err: () => null,\n        });\n    }\n\n    /**\n     * Returns the error when this is a failure, or null when this is a success.\n     */\n    errorOrNull(): E | null {\n        return this.match({\n            ok: () => null,\n            err: (error) => error,\n        });\n    }\n\n    /**\n     * Returns the value when this is a success, or throws the error when this is a failure.\n     */\n    getOrThrow(): T {\n        return this.match({\n            ok: (value) => value,\n            err: (error) => {\n                throw toError(error);\n            },\n        });\n    }\n\n    /**\n     * Transforms the success value using the provided function. Keeps the error when this is a failure.\n     *\n     * Exceptions thrown by `transform` propagate; they are not captured into an `Err`.\n     */\n    map<R>(transform: (value: T) => R): Result<R, E> {\n        return this.match<Result<R, E>>({\n            ok: (value) => Result.ok(transform(value)),\n            // TS does not \"see\" variance here; the cast is intentional and safe:\n            // Err carries no T, so it can be widened to Result<R, E> safely.\n            err: (error) => Result.err(error) as unknown as Result<R, E>,\n        });\n    }\n\n    /**\n     * Transforms the error using the provided function. Keeps the value when this is a success.\n     *\n     * Exceptions thrown by `transform` propagate; they are not captured into an `Err`.\n     */\n    mapError<F>(transform: (error: E) => F): Result<T, F> {\n        return this.match<Result<T, F>>({\n            // Ok carries no E, so it can be widened to Result<T, F>.\n            ok: (value) => Result.ok(value) as unknown as Result<T, F>,\n            err: (error) => Result.err(transform(error)),\n        });\n    }\n\n    /**\n     * Chains another operation that returns a Result when this result is a success.\n     *\n     * Exceptions thrown by `transform` propagate; they are not captured into an `Err`.\n     */\n    flatMap<R>(transform: (value: T) => Result<R, E>): Result<R, E> {\n        return this.match<Result<R, E>>({\n            ok: (value) => transform(value),\n            err: (error) => Result.err(error) as unknown as Result<R, E>,\n        });\n    }\n}\n\n/**\n * Success variant of Result.\n *\n * The instance is frozen, but the freeze is shallow: a contained mutable\n * object is not frozen.\n */\nexport class Ok<T> extends Result<T, never> {\n    public readonly value: T;\n\n    constructor(value: T) {\n        super();\n        this.value = value;\n        Object.freeze(this);\n    }\n\n    isOk(): this is Ok<T> {\n        return true;\n    }\n\n    isErr(): this is Err<never> {\n        return false;\n    }\n\n    match<R>(handlers: { ok: (value: T) => R; err: (error: never) => R }): R {\n        return handlers.ok(this.value);\n    }\n}\n\n/**\n * Error variant of Result.\n */\nexport class Err<E> extends Result<never, E> {\n    public readonly error: E;\n\n    constructor(error: E) {\n        super();\n        this.error = error;\n        Object.freeze(this);\n    }\n\n    isOk(): this is Ok<never> {\n        return false;\n    }\n\n    isErr(): this is Err<E> {\n        return true;\n    }\n\n    match<R>(handlers: { ok: (value: never) => R; err: (error: E) => R }): R {\n        return handlers.err(this.error);\n    }\n}\n\n/**\n * Coerces an arbitrary error value into an Error for `getOrThrow`, preserving\n * the original structured payload as `cause` so nothing is lost when `E` is a\n * plain object/DTO rather than an Error.\n */\nfunction toError(error: unknown): Error {\n    if (error instanceof Error) return error;\n    if (typeof error === \"string\") return new Error(error);\n    let message: string | undefined;\n    try {\n        message = JSON.stringify(error);\n    } catch {\n        // circular / BigInt / etc.\n    }\n    const wrapped = new Error(message ?? String(error));\n    // Attach the original payload as `cause` (assigned, not passed to the\n    // ES2022 constructor option, to stay within the ES2020 lib target).\n    (wrapped as Error & { cause?: unknown }).cause = error;\n    return wrapped;\n}\n"],"mappings":";;;;;AAIA,IAAsB,SAAtB,MAAsB,OAAa;CAC/B,cAAwB,CAExB;;;;CAKA,OAAO,GAAM,OAA4B;EACrC,OAAO,IAAI,GAAG,KAAK;CACvB;;;;CAKA,OAAO,IAAO,OAA4B;EACtC,OAAO,IAAI,IAAI,KAAK;CACxB;;;;;;;CA0BA,YAAsB;EAClB,OAAO,KAAK,MAAM;GACd,KAAK,UAAU;GACf,WAAW;EACf,CAAC;CACL;;;;CAKA,cAAwB;EACpB,OAAO,KAAK,MAAM;GACd,UAAU;GACV,MAAM,UAAU;EACpB,CAAC;CACL;;;;CAKA,aAAgB;EACZ,OAAO,KAAK,MAAM;GACd,KAAK,UAAU;GACf,MAAM,UAAU;IACZ,MAAM,QAAQ,KAAK;GACvB;EACJ,CAAC;CACL;;;;;;CAOA,IAAO,WAA0C;EAC7C,OAAO,KAAK,MAAoB;GAC5B,KAAK,UAAU,OAAO,GAAG,UAAU,KAAK,CAAC;GAGzC,MAAM,UAAU,OAAO,IAAI,KAAK;EACpC,CAAC;CACL;;;;;;CAOA,SAAY,WAA0C;EAClD,OAAO,KAAK,MAAoB;GAE5B,KAAK,UAAU,OAAO,GAAG,KAAK;GAC9B,MAAM,UAAU,OAAO,IAAI,UAAU,KAAK,CAAC;EAC/C,CAAC;CACL;;;;;;CAOA,QAAW,WAAqD;EAC5D,OAAO,KAAK,MAAoB;GAC5B,KAAK,UAAU,UAAU,KAAK;GAC9B,MAAM,UAAU,OAAO,IAAI,KAAK;EACpC,CAAC;CACL;AACJ;;;;;;;AAQA,IAAa,KAAb,cAA2B,OAAiB;CAGxC,YAAY,OAAU;EAClB,MAAM;EACN,KAAK,QAAQ;EACb,OAAO,OAAO,IAAI;CACtB;CAEA,OAAsB;EAClB,OAAO;CACX;CAEA,QAA4B;EACxB,OAAO;CACX;CAEA,MAAS,UAAgE;EACrE,OAAO,SAAS,GAAG,KAAK,KAAK;CACjC;AACJ;;;;AAKA,IAAa,MAAb,cAA4B,OAAiB;CAGzC,YAAY,OAAU;EAClB,MAAM;EACN,KAAK,QAAQ;EACb,OAAO,OAAO,IAAI;CACtB;CAEA,OAA0B;EACtB,OAAO;CACX;CAEA,QAAwB;EACpB,OAAO;CACX;CAEA,MAAS,UAAgE;EACrE,OAAO,SAAS,IAAI,KAAK,KAAK;CAClC;AACJ;;;;;;AAOA,SAAS,QAAQ,OAAuB;CACpC,IAAI,iBAAiB,OAAO,OAAO;CACnC,IAAI,OAAO,UAAU,UAAU,OAAO,IAAI,MAAM,KAAK;CACrD,IAAI;CACJ,IAAI;EACA,UAAU,KAAK,UAAU,KAAK;CAClC,QAAQ,CAER;CACA,MAAM,UAAU,IAAI,MAAM,WAAW,OAAO,KAAK,CAAC;CAGlD,QAAyC,QAAQ;CACjD,OAAO;AACX"}

package/dist/result.d.cts

@@ -30,6 +30,9 @@ declare abstract class Result<T, E> {
   }): R;
   /**
    * Returns the value when this is success, or null when this is an error.
+   *
+   * Note: an `Ok(null)` also returns `null`, indistinguishable from an `Err`.
+   * Use `match`/`isOk` when that distinction matters.
    */
   getOrNull(): T | null;
   /**
@@ -42,19 +45,28 @@ declare abstract class Result<T, E> {
   getOrThrow(): T;
   /**
    * Transforms the success value using the provided function. Keeps the error when this is a failure.
+   *
+   * Exceptions thrown by `transform` propagate; they are not captured into an `Err`.
    */
   map<R>(transform: (value: T) => R): Result<R, E>;
   /**
    * Transforms the error using the provided function. Keeps the value when this is a success.
+   *
+   * Exceptions thrown by `transform` propagate; they are not captured into an `Err`.
    */
   mapError<F>(transform: (error: E) => F): Result<T, F>;
   /**
    * Chains another operation that returns a Result when this result is a success.
+   *
+   * Exceptions thrown by `transform` propagate; they are not captured into an `Err`.
    */
   flatMap<R>(transform: (value: T) => Result<R, E>): Result<R, E>;
 }
 /**
  * Success variant of Result.
+ *
+ * The instance is frozen, but the freeze is shallow: a contained mutable
+ * object is not frozen.
  */
 declare class Ok<T> extends Result<T, never> {
   readonly value: T;

package/dist/result.d.ts

@@ -30,6 +30,9 @@ declare abstract class Result<T, E> {
   }): R;
   /**
    * Returns the value when this is success, or null when this is an error.
+   *
+   * Note: an `Ok(null)` also returns `null`, indistinguishable from an `Err`.
+   * Use `match`/`isOk` when that distinction matters.
    */
   getOrNull(): T | null;
   /**
@@ -42,19 +45,28 @@ declare abstract class Result<T, E> {
   getOrThrow(): T;
   /**
    * Transforms the success value using the provided function. Keeps the error when this is a failure.
+   *
+   * Exceptions thrown by `transform` propagate; they are not captured into an `Err`.
    */
   map<R>(transform: (value: T) => R): Result<R, E>;
   /**
    * Transforms the error using the provided function. Keeps the value when this is a success.
+   *
+   * Exceptions thrown by `transform` propagate; they are not captured into an `Err`.
    */
   mapError<F>(transform: (error: E) => F): Result<T, F>;
   /**
    * Chains another operation that returns a Result when this result is a success.
+   *
+   * Exceptions thrown by `transform` propagate; they are not captured into an `Err`.
    */
   flatMap<R>(transform: (value: T) => Result<R, E>): Result<R, E>;
 }
 /**
  * Success variant of Result.
+ *
+ * The instance is frozen, but the freeze is shallow: a contained mutable
+ * object is not frozen.
  */
 declare class Ok<T> extends Result<T, never> {
   readonly value: T;

package/dist/result.js

@@ -19,6 +19,9 @@ var Result = class Result {
 	}
 	/**
 	* Returns the value when this is success, or null when this is an error.
+	*
+	* Note: an `Ok(null)` also returns `null`, indistinguishable from an `Err`.
+	* Use `match`/`isOk` when that distinction matters.
 	*/
 	getOrNull() {
 		return this.match({
@@ -42,12 +45,14 @@ var Result = class Result {
 		return this.match({
 			ok: (value) => value,
 			err: (error) => {
-				throw error instanceof Error ? error : new Error(String(error));
+				throw toError(error);
 			}
 		});
 	}
 	/**
 	* Transforms the success value using the provided function. Keeps the error when this is a failure.
+	*
+	* Exceptions thrown by `transform` propagate; they are not captured into an `Err`.
 	*/
 	map(transform) {
 		return this.match({
@@ -57,6 +62,8 @@ var Result = class Result {
 	}
 	/**
 	* Transforms the error using the provided function. Keeps the value when this is a success.
+	*
+	* Exceptions thrown by `transform` propagate; they are not captured into an `Err`.
 	*/
 	mapError(transform) {
 		return this.match({
@@ -66,6 +73,8 @@ var Result = class Result {
 	}
 	/**
 	* Chains another operation that returns a Result when this result is a success.
+	*
+	* Exceptions thrown by `transform` propagate; they are not captured into an `Err`.
 	*/
 	flatMap(transform) {
 		return this.match({
@@ -76,6 +85,9 @@ var Result = class Result {
 };
 /**
 * Success variant of Result.
+*
+* The instance is frozen, but the freeze is shallow: a contained mutable
+* object is not frozen.
 */
 var Ok = class extends Result {
 	constructor(value) {
@@ -112,6 +124,22 @@ var Err = class extends Result {
 		return handlers.err(this.error);
 	}
 };
+/**
+* Coerces an arbitrary error value into an Error for `getOrThrow`, preserving
+* the original structured payload as `cause` so nothing is lost when `E` is a
+* plain object/DTO rather than an Error.
+*/
+function toError(error) {
+	if (error instanceof Error) return error;
+	if (typeof error === "string") return new Error(error);
+	let message;
+	try {
+		message = JSON.stringify(error);
+	} catch {}
+	const wrapped = new Error(message ?? String(error));
+	wrapped.cause = error;
+	return wrapped;
+}
 //#endregion
 export { Ok as n, Result as r, Err as t };
 

package/dist/result.js.map

@@ -1 +1 @@
-{"version":3,"file":"result.js","names":[],"sources":["../src/core/result/result.ts"],"sourcesContent":["/**\n * Represents the outcome of an operation that may succeed or fail.\n * Useful for avoiding excessive exceptions and making error flows explicit.\n */\nexport abstract class Result<T, E> {\n    protected constructor() {\n        // prevent direct instantiation\n    }\n\n    /**\n     * Creates a success result containing a value.\n     */\n    static ok<T>(value: T): Result<T, never> {\n        return new Ok(value);\n    }\n\n    /**\n     * Creates an error result containing an error object.\n     */\n    static err<E>(error: E): Result<never, E> {\n        return new Err(error);\n    }\n\n    /**\n     * Returns true when this is a success result.\n     */\n    abstract isOk(): this is Ok<T>;\n\n    /**\n     * Returns true when this is an error result.\n     */\n    abstract isErr(): this is Err<E>;\n\n    /**\n     * Runs a handler based on the result state (similar to pattern matching).\n     */\n    abstract match<R>(handlers: {\n        ok: (value: T) => R;\n        err: (error: E) => R;\n    }): R;\n\n    /**\n     * Returns the value when this is success, or null when this is an error.\n     */\n    getOrNull(): T | null {\n        return this.match({\n            ok: (value) => value,\n            err: () => null,\n        });\n    }\n\n    /**\n     * Returns the error when this is a failure, or null when this is a success.\n     */\n    errorOrNull(): E | null {\n        return this.match({\n            ok: () => null,\n            err: (error) => error,\n        });\n    }\n\n    /**\n     * Returns the value when this is a success, or throws the error when this is a failure.\n     */\n    getOrThrow(): T {\n        return this.match({\n            ok: (value) => value,\n            err: (error) => {\n                throw error instanceof Error ? error : new Error(String(error));\n            },\n        });\n    }\n\n    /**\n     * Transforms the success value using the provided function. Keeps the error when this is a failure.\n     */\n    map<R>(transform: (value: T) => R): Result<R, E> {\n        return this.match<Result<R, E>>({\n            ok: (value) => Result.ok(transform(value)),\n            // TS does not \"see\" variance here; the cast is intentional and safe:\n            // Err carries no T, so it can be widened to Result<R, E> safely.\n            err: (error) => Result.err(error) as unknown as Result<R, E>,\n        });\n    }\n\n    /**\n     * Transforms the error using the provided function. Keeps the value when this is a success.\n     */\n    mapError<F>(transform: (error: E) => F): Result<T, F> {\n        return this.match<Result<T, F>>({\n            // Ok carries no E, so it can be widened to Result<T, F>.\n            ok: (value) => Result.ok(value) as unknown as Result<T, F>,\n            err: (error) => Result.err(transform(error)),\n        });\n    }\n\n    /**\n     * Chains another operation that returns a Result when this result is a success.\n     */\n    flatMap<R>(transform: (value: T) => Result<R, E>): Result<R, E> {\n        return this.match<Result<R, E>>({\n            ok: (value) => transform(value),\n            err: (error) => Result.err(error) as unknown as Result<R, E>,\n        });\n    }\n}\n\n/**\n * Success variant of Result.\n */\nexport class Ok<T> extends Result<T, never> {\n    public readonly value: T;\n\n    constructor(value: T) {\n        super();\n        this.value = value;\n        Object.freeze(this);\n    }\n\n    isOk(): this is Ok<T> {\n        return true;\n    }\n\n    isErr(): this is Err<never> {\n        return false;\n    }\n\n    match<R>(handlers: { ok: (value: T) => R; err: (error: never) => R }): R {\n        return handlers.ok(this.value);\n    }\n}\n\n/**\n * Error variant of Result.\n */\nexport class Err<E> extends Result<never, E> {\n    public readonly error: E;\n\n    constructor(error: E) {\n        super();\n        this.error = error;\n        Object.freeze(this);\n    }\n\n    isOk(): this is Ok<never> {\n        return false;\n    }\n\n    isErr(): this is Err<E> {\n        return true;\n    }\n\n    match<R>(handlers: { ok: (value: never) => R; err: (error: E) => R }): R {\n        return handlers.err(this.error);\n    }\n}\n"],"mappings":";;;;;AAIA,IAAsB,SAAtB,MAAsB,OAAa;CAC/B,cAAwB,CAExB;;;;CAKA,OAAO,GAAM,OAA4B;EACrC,OAAO,IAAI,GAAG,KAAK;CACvB;;;;CAKA,OAAO,IAAO,OAA4B;EACtC,OAAO,IAAI,IAAI,KAAK;CACxB;;;;CAuBA,YAAsB;EAClB,OAAO,KAAK,MAAM;GACd,KAAK,UAAU;GACf,WAAW;EACf,CAAC;CACL;;;;CAKA,cAAwB;EACpB,OAAO,KAAK,MAAM;GACd,UAAU;GACV,MAAM,UAAU;EACpB,CAAC;CACL;;;;CAKA,aAAgB;EACZ,OAAO,KAAK,MAAM;GACd,KAAK,UAAU;GACf,MAAM,UAAU;IACZ,MAAM,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;GAClE;EACJ,CAAC;CACL;;;;CAKA,IAAO,WAA0C;EAC7C,OAAO,KAAK,MAAoB;GAC5B,KAAK,UAAU,OAAO,GAAG,UAAU,KAAK,CAAC;GAGzC,MAAM,UAAU,OAAO,IAAI,KAAK;EACpC,CAAC;CACL;;;;CAKA,SAAY,WAA0C;EAClD,OAAO,KAAK,MAAoB;GAE5B,KAAK,UAAU,OAAO,GAAG,KAAK;GAC9B,MAAM,UAAU,OAAO,IAAI,UAAU,KAAK,CAAC;EAC/C,CAAC;CACL;;;;CAKA,QAAW,WAAqD;EAC5D,OAAO,KAAK,MAAoB;GAC5B,KAAK,UAAU,UAAU,KAAK;GAC9B,MAAM,UAAU,OAAO,IAAI,KAAK;EACpC,CAAC;CACL;AACJ;;;;AAKA,IAAa,KAAb,cAA2B,OAAiB;CAGxC,YAAY,OAAU;EAClB,MAAM;EACN,KAAK,QAAQ;EACb,OAAO,OAAO,IAAI;CACtB;CAEA,OAAsB;EAClB,OAAO;CACX;CAEA,QAA4B;EACxB,OAAO;CACX;CAEA,MAAS,UAAgE;EACrE,OAAO,SAAS,GAAG,KAAK,KAAK;CACjC;AACJ;;;;AAKA,IAAa,MAAb,cAA4B,OAAiB;CAGzC,YAAY,OAAU;EAClB,MAAM;EACN,KAAK,QAAQ;EACb,OAAO,OAAO,IAAI;CACtB;CAEA,OAA0B;EACtB,OAAO;CACX;CAEA,QAAwB;EACpB,OAAO;CACX;CAEA,MAAS,UAAgE;EACrE,OAAO,SAAS,IAAI,KAAK,KAAK;CAClC;AACJ"}
+{"version":3,"file":"result.js","names":[],"sources":["../src/core/result/result.ts"],"sourcesContent":["/**\n * Represents the outcome of an operation that may succeed or fail.\n * Useful for avoiding excessive exceptions and making error flows explicit.\n */\nexport abstract class Result<T, E> {\n    protected constructor() {\n        // prevent direct instantiation\n    }\n\n    /**\n     * Creates a success result containing a value.\n     */\n    static ok<T>(value: T): Result<T, never> {\n        return new Ok(value);\n    }\n\n    /**\n     * Creates an error result containing an error object.\n     */\n    static err<E>(error: E): Result<never, E> {\n        return new Err(error);\n    }\n\n    /**\n     * Returns true when this is a success result.\n     */\n    abstract isOk(): this is Ok<T>;\n\n    /**\n     * Returns true when this is an error result.\n     */\n    abstract isErr(): this is Err<E>;\n\n    /**\n     * Runs a handler based on the result state (similar to pattern matching).\n     */\n    abstract match<R>(handlers: {\n        ok: (value: T) => R;\n        err: (error: E) => R;\n    }): R;\n\n    /**\n     * Returns the value when this is success, or null when this is an error.\n     *\n     * Note: an `Ok(null)` also returns `null`, indistinguishable from an `Err`.\n     * Use `match`/`isOk` when that distinction matters.\n     */\n    getOrNull(): T | null {\n        return this.match({\n            ok: (value) => value,\n            err: () => null,\n        });\n    }\n\n    /**\n     * Returns the error when this is a failure, or null when this is a success.\n     */\n    errorOrNull(): E | null {\n        return this.match({\n            ok: () => null,\n            err: (error) => error,\n        });\n    }\n\n    /**\n     * Returns the value when this is a success, or throws the error when this is a failure.\n     */\n    getOrThrow(): T {\n        return this.match({\n            ok: (value) => value,\n            err: (error) => {\n                throw toError(error);\n            },\n        });\n    }\n\n    /**\n     * Transforms the success value using the provided function. Keeps the error when this is a failure.\n     *\n     * Exceptions thrown by `transform` propagate; they are not captured into an `Err`.\n     */\n    map<R>(transform: (value: T) => R): Result<R, E> {\n        return this.match<Result<R, E>>({\n            ok: (value) => Result.ok(transform(value)),\n            // TS does not \"see\" variance here; the cast is intentional and safe:\n            // Err carries no T, so it can be widened to Result<R, E> safely.\n            err: (error) => Result.err(error) as unknown as Result<R, E>,\n        });\n    }\n\n    /**\n     * Transforms the error using the provided function. Keeps the value when this is a success.\n     *\n     * Exceptions thrown by `transform` propagate; they are not captured into an `Err`.\n     */\n    mapError<F>(transform: (error: E) => F): Result<T, F> {\n        return this.match<Result<T, F>>({\n            // Ok carries no E, so it can be widened to Result<T, F>.\n            ok: (value) => Result.ok(value) as unknown as Result<T, F>,\n            err: (error) => Result.err(transform(error)),\n        });\n    }\n\n    /**\n     * Chains another operation that returns a Result when this result is a success.\n     *\n     * Exceptions thrown by `transform` propagate; they are not captured into an `Err`.\n     */\n    flatMap<R>(transform: (value: T) => Result<R, E>): Result<R, E> {\n        return this.match<Result<R, E>>({\n            ok: (value) => transform(value),\n            err: (error) => Result.err(error) as unknown as Result<R, E>,\n        });\n    }\n}\n\n/**\n * Success variant of Result.\n *\n * The instance is frozen, but the freeze is shallow: a contained mutable\n * object is not frozen.\n */\nexport class Ok<T> extends Result<T, never> {\n    public readonly value: T;\n\n    constructor(value: T) {\n        super();\n        this.value = value;\n        Object.freeze(this);\n    }\n\n    isOk(): this is Ok<T> {\n        return true;\n    }\n\n    isErr(): this is Err<never> {\n        return false;\n    }\n\n    match<R>(handlers: { ok: (value: T) => R; err: (error: never) => R }): R {\n        return handlers.ok(this.value);\n    }\n}\n\n/**\n * Error variant of Result.\n */\nexport class Err<E> extends Result<never, E> {\n    public readonly error: E;\n\n    constructor(error: E) {\n        super();\n        this.error = error;\n        Object.freeze(this);\n    }\n\n    isOk(): this is Ok<never> {\n        return false;\n    }\n\n    isErr(): this is Err<E> {\n        return true;\n    }\n\n    match<R>(handlers: { ok: (value: never) => R; err: (error: E) => R }): R {\n        return handlers.err(this.error);\n    }\n}\n\n/**\n * Coerces an arbitrary error value into an Error for `getOrThrow`, preserving\n * the original structured payload as `cause` so nothing is lost when `E` is a\n * plain object/DTO rather than an Error.\n */\nfunction toError(error: unknown): Error {\n    if (error instanceof Error) return error;\n    if (typeof error === \"string\") return new Error(error);\n    let message: string | undefined;\n    try {\n        message = JSON.stringify(error);\n    } catch {\n        // circular / BigInt / etc.\n    }\n    const wrapped = new Error(message ?? String(error));\n    // Attach the original payload as `cause` (assigned, not passed to the\n    // ES2022 constructor option, to stay within the ES2020 lib target).\n    (wrapped as Error & { cause?: unknown }).cause = error;\n    return wrapped;\n}\n"],"mappings":";;;;;AAIA,IAAsB,SAAtB,MAAsB,OAAa;CAC/B,cAAwB,CAExB;;;;CAKA,OAAO,GAAM,OAA4B;EACrC,OAAO,IAAI,GAAG,KAAK;CACvB;;;;CAKA,OAAO,IAAO,OAA4B;EACtC,OAAO,IAAI,IAAI,KAAK;CACxB;;;;;;;CA0BA,YAAsB;EAClB,OAAO,KAAK,MAAM;GACd,KAAK,UAAU;GACf,WAAW;EACf,CAAC;CACL;;;;CAKA,cAAwB;EACpB,OAAO,KAAK,MAAM;GACd,UAAU;GACV,MAAM,UAAU;EACpB,CAAC;CACL;;;;CAKA,aAAgB;EACZ,OAAO,KAAK,MAAM;GACd,KAAK,UAAU;GACf,MAAM,UAAU;IACZ,MAAM,QAAQ,KAAK;GACvB;EACJ,CAAC;CACL;;;;;;CAOA,IAAO,WAA0C;EAC7C,OAAO,KAAK,MAAoB;GAC5B,KAAK,UAAU,OAAO,GAAG,UAAU,KAAK,CAAC;GAGzC,MAAM,UAAU,OAAO,IAAI,KAAK;EACpC,CAAC;CACL;;;;;;CAOA,SAAY,WAA0C;EAClD,OAAO,KAAK,MAAoB;GAE5B,KAAK,UAAU,OAAO,GAAG,KAAK;GAC9B,MAAM,UAAU,OAAO,IAAI,UAAU,KAAK,CAAC;EAC/C,CAAC;CACL;;;;;;CAOA,QAAW,WAAqD;EAC5D,OAAO,KAAK,MAAoB;GAC5B,KAAK,UAAU,UAAU,KAAK;GAC9B,MAAM,UAAU,OAAO,IAAI,KAAK;EACpC,CAAC;CACL;AACJ;;;;;;;AAQA,IAAa,KAAb,cAA2B,OAAiB;CAGxC,YAAY,OAAU;EAClB,MAAM;EACN,KAAK,QAAQ;EACb,OAAO,OAAO,IAAI;CACtB;CAEA,OAAsB;EAClB,OAAO;CACX;CAEA,QAA4B;EACxB,OAAO;CACX;CAEA,MAAS,UAAgE;EACrE,OAAO,SAAS,GAAG,KAAK,KAAK;CACjC;AACJ;;;;AAKA,IAAa,MAAb,cAA4B,OAAiB;CAGzC,YAAY,OAAU;EAClB,MAAM;EACN,KAAK,QAAQ;EACb,OAAO,OAAO,IAAI;CACtB;CAEA,OAA0B;EACtB,OAAO;CACX;CAEA,QAAwB;EACpB,OAAO;CACX;CAEA,MAAS,UAAgE;EACrE,OAAO,SAAS,IAAI,KAAK,KAAK;CAClC;AACJ;;;;;;AAOA,SAAS,QAAQ,OAAuB;CACpC,IAAI,iBAAiB,OAAO,OAAO;CACnC,IAAI,OAAO,UAAU,UAAU,OAAO,IAAI,MAAM,KAAK;CACrD,IAAI;CACJ,IAAI;EACA,UAAU,KAAK,UAAU,KAAK;CAClC,QAAQ,CAER;CACA,MAAM,UAAU,IAAI,MAAM,WAAW,OAAO,KAAK,CAAC;CAGlD,QAAyC,QAAQ;CACjD,OAAO;AACX"}

package/dist/rule.cjs

@@ -97,46 +97,73 @@ const ENGINE_VERSION = 1;
 * "errors as values" contract of `RbacAuthorizer`/`GateEngineV1`.
 *
 * A denial maps to {@link AuthorizationError.policyDenied}, attributed to the
-* deciding rule's `id`/`version`; a condition-evaluation failure (a missing
+* deciding rule's `id`/`version`. A condition-evaluation failure (a missing
 * attribute, a wrong-typed operand) fails closed as
-* {@link AuthorizationError.forbidden}. Loading the dynamic attributes is the
-* consumer's job (behind an `AbacAuthorizerPort` adapter); this class only decides.
+* {@link AuthorizationError.forbidden} — also attributed to the culprit rule's
+* `id`/`version` — unless the set opts into `onEvaluationError: "skip-rule"`, in
+* which case the unevaluable rule is skipped and the rest decide. Every resolved
+* decision (PERMIT and DENY) is emitted best-effort through the configured
+* reporter as an `abac-decision` event (silent by default). Timestamps come from
+* an injectable `clock` (default `() => new Date()`), so the decisor is pure
+* given one. Loading the dynamic attributes is the consumer's job (behind an
+* `AbacAuthorizerPort` adapter); this class only decides.
 */
 var AbacAuthorizer = class {
 	constructor(params = {}) {
 		this.coreConfig = params.coreConfig ?? require_condition_evaluator.coreConfig;
+		this.clock = params.clock ?? (() => /* @__PURE__ */ new Date());
 	}
 	authorize(request, policies) {
 		const evaluator = new require_condition_evaluator.ConditionEvaluatorV1(abacContext(request), this.coreConfig.getConditionEvaluationOptions(ENGINE_VERSION));
 		const applicable = [];
 		for (const rule of policies.rules) {
 			const matched = evaluator.evaluate(rule.condition);
-			if (matched.isErr()) return require_result.Result.err(require_authorization_error.AuthorizationError.forbidden({
-				action: request.action,
-				resource: request.resource,
-				actor: { userId: request.actor.raw },
-				details: matched.errorOrNull() ?? void 0
-			}));
+			if (matched.isErr()) {
+				if (policies.onEvaluationError === "skip-rule") continue;
+				return require_result.Result.err(require_authorization_error.AuthorizationError.forbidden({
+					action: request.action,
+					resource: request.resource,
+					actor: { actorId: request.actor.raw },
+					policyId: rule.id,
+					policyVersion: rule.version,
+					details: matched.errorOrNull() ?? void 0
+				}));
+			}
 			if (matched.getOrThrow()) applicable.push(rule);
 		}
 		const { effect, decidingRule } = combine(policies.algorithm, applicable, policies.defaultEffect);
+		this.reportDecision(request, policies, effect, decidingRule);
 		if (effect === "PERMIT") return require_result.Result.ok({
 			action: request.action,
 			effect: "PERMIT",
 			matchedRule: decidingRule?.id ?? "<default>",
 			algorithm: policies.algorithm,
-			grantedAtIso: (/* @__PURE__ */ new Date()).toISOString()
+			grantedAtIso: this.clock().toISOString()
 		});
 		return require_result.Result.err(require_authorization_error.AuthorizationError.policyDenied({
 			policyId: decidingRule?.id ?? "<default-deny>",
 			policyVersion: decidingRule?.version ?? 0,
-			evaluatedAtIso: (/* @__PURE__ */ new Date()).toISOString(),
+			evaluatedAtIso: this.clock().toISOString(),
 			action: request.action,
 			resource: request.resource,
-			actor: { userId: request.actor.raw },
+			actor: { actorId: request.actor.raw },
 			reasonCode: decidingRule?.id
 		}));
 	}
+	reportDecision(request, policies, effect, decidingRule) {
+		this.coreConfig.reportSafely({
+			kind: "abac-decision",
+			level: "info",
+			action: request.action,
+			resource: request.resource,
+			actorId: request.actor.raw,
+			effect,
+			decidingRuleId: decidingRule?.id ?? (effect === "PERMIT" ? "<default>" : "<default-deny>"),
+			decidingRuleVersion: decidingRule?.version,
+			algorithm: policies.algorithm,
+			occurredAt: this.clock()
+		});
+	}
 };
 //#endregion
 //#region src/core/abac/composite-authorizer.ts
@@ -163,26 +190,43 @@ var CompositeAuthorizer = class {
 };
 //#endregion
 //#region src/core/abac/domain/policy-set.ts
+const POLICY_SET_FIELD = require_validation_field.ValidationField.of("abacPolicySet");
 /**
 * An ordered collection of {@link AbacRule}s plus how to combine them
-* ({@link CombiningAlgorithm}) and what to decide when no rule applies
-* ({@link defaultEffect}). This is where ABAC goes beyond a single gate
+* ({@link CombiningAlgorithm}), what to decide when no rule applies
+* ({@link defaultEffect}), and how to react to an unevaluable rule
+* ({@link onEvaluationError}). This is where ABAC goes beyond a single gate
 * condition: several PERMIT/DENY rules resolved by an explicit algorithm.
 *
-* Closed by default — the combining algorithm defaults to `"deny-overrides"` and
-* the default effect to `"DENY"`, so a request matching nothing is denied. A
-* plain holder (not a value object); build through {@link of}.
+* Closed by default — the combining algorithm defaults to `"deny-overrides"`,
+* the default effect to `"DENY"`, and evaluation errors to `"fail-closed"`, so a
+* request matching nothing (or hitting a technical error) is denied. A plain
+* holder (not a value object); build through {@link of}.
 */
 var AbacPolicySet = class AbacPolicySet {
-	constructor(_rules, _algorithm, _defaultEffect) {
+	constructor(_rules, _algorithm, _defaultEffect, _onEvaluationError) {
 		this._rules = _rules;
 		this._algorithm = _algorithm;
 		this._defaultEffect = _defaultEffect;
+		this._onEvaluationError = _onEvaluationError;
 		Object.freeze(this._rules);
 		Object.freeze(this);
 	}
+	/**
+	* Builds a policy set. Rejects duplicate rule ids with
+	* {@link InvalidValueException} so a denial's `policyId` attribution is
+	* unambiguous.
+	*/
 	static of(rules, options = {}) {
-		return new AbacPolicySet([...rules], options.algorithm ?? "deny-overrides", options.defaultEffect ?? "DENY");
+		AbacPolicySet.assertUniqueIds(rules);
+		return new AbacPolicySet([...rules], options.algorithm ?? "deny-overrides", options.defaultEffect ?? "DENY", options.onEvaluationError ?? "fail-closed");
+	}
+	static assertUniqueIds(rules) {
+		const seen = /* @__PURE__ */ new Set();
+		for (const rule of rules) {
+			if (seen.has(rule.id)) throw new require_validation_exception.InvalidValueException(POLICY_SET_FIELD.nested("rules"), require_validation_code.ValidationCode.ALREADY_EXISTS, `abac policy set has duplicate rule id "${rule.id}"; ids must be unique for unambiguous audit attribution`);
+			seen.add(rule.id);
+		}
 	}
 	get rules() {
 		return this._rules;
@@ -193,11 +237,13 @@ var AbacPolicySet = class AbacPolicySet {
 	get defaultEffect() {
 		return this._defaultEffect;
 	}
+	get onEvaluationError() {
+		return this._onEvaluationError;
+	}
 };
 //#endregion
-//#region src/core/abac/domain/rule.ts
-const RULE_FIELD = require_validation_field.ValidationField.of("abacRule");
-const CONDITION_OPS = new Set([
+//#region src/core/policies/engines/v1/condition-types.ts
+const CONDITION_OPS = [
 	"eq",
 	"neq",
 	"gt",
@@ -208,7 +254,11 @@ const CONDITION_OPS = new Set([
 	"notIn",
 	"isNull",
 	"isNotNull"
-]);
+];
+//#endregion
+//#region src/core/abac/domain/rule.ts
+const RULE_FIELD = require_validation_field.ValidationField.of("abacRule");
+const SUPPORTED_OPS = new Set(CONDITION_OPS);
 const RULE_EFFECTS = new Set(["PERMIT", "DENY"]);
 function isPlainObject(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -225,6 +275,26 @@ function isPlainObject(value) {
 * authored in TypeScript — trusted data, not untrusted JSON — the structural
 * check is a hand-rolled walk of the condition tree rather than a schema parse.
 * Build one through {@link of}; the constructor is private.
+*
+* **Attribute semantics a rule author must know (the condition is evaluated by
+* the shared gate/compute engine, whose runtime rules apply here too):**
+* - **A referenced attribute that is *absent* from the request is a technical
+*   evaluation error, not a non-match.** By default (`onEvaluationError:
+*   "fail-closed"` on the {@link AbacPolicySet}) that error fails the *entire*
+*   decision closed — so adding a rule that reads an attribute a given call site
+*   does not yet populate makes that call site start returning `forbidden`,
+*   *even for requests the older rules used to permit*. Choose
+*   `onEvaluationError: "skip-rule"` on the set to skip an unevaluable rule
+*   instead of failing the whole set.
+* - **`isNull` / `isNotNull` test for an explicit `null`/`undefined` *value*, not
+*   for a missing key.** A key that is absent from the bag never reaches the
+*   operator — it short-circuits to the missing-attribute error above. To match
+*   "no deletedAt", the consumer must put `deletedAt: null` in the bag, not omit
+*   it. Pass `allowNull: true` on a relational leaf to treat a present `null` as
+*   a non-match instead of an error.
+* - **Date comparison operands must be strict ISO-8601 UTC**
+*   (`YYYY-MM-DDTHH:mm:ss.sssZ`); a bare `"2026-07-09"` or an offset like
+*   `+00:00` is rejected as an invalid operand and fails closed.
 */
 var AbacRule = class AbacRule extends require_value_object.ValueObject {
 	constructor(props) {
@@ -258,7 +328,7 @@ var AbacRule = class AbacRule extends require_value_object.ValueObject {
 		}
 		if ("field" in node && "op" in node) {
 			if (typeof node.field !== "string" || node.field.trim().length === 0) AbacRule.rejectCondition(`abac rule condition leaf "field" must be a non-empty string, got "${String(node.field)}"`);
-			if (typeof node.op !== "string" || !CONDITION_OPS.has(node.op)) AbacRule.rejectCondition(`abac rule condition leaf "op" is not a supported operator, got "${String(node.op)}"`);
+			if (typeof node.op !== "string" || !SUPPORTED_OPS.has(node.op)) AbacRule.rejectCondition(`abac rule condition leaf "op" is not a supported operator, got "${String(node.op)}"`);
 			return;
 		}
 		AbacRule.rejectCondition("abac rule condition must be a leaf { field, op } or an { and | or | not } node");