@gilles-coudert/pure-trace 1.0.5 → 1.0.7

package/README.md

@@ -56,7 +56,7 @@ if (result.isSuccess()) {
 ## Mental model
 
 - A **Result** is either `Success<S>` or `Failure`
-- A **Failure** contains **error messages**
+- A **Failure** contains **error message**
 - Both Success and Failure can accumulate **trace messages**
 - Errors are just messages with `kind: "error"`
 
@@ -68,6 +68,8 @@ type Message = {
     type: string;
     code: string;
     data?: unknown;
+    issuer?: string; // optional: who emitted the message
+    localizedMessage?: string; // optional: localized user message
 };
 ```
 
@@ -78,7 +80,13 @@ type Message = {
 ```ts
 const ok = new Success(42);
 
-const ko = generateFailure('processError', 'notFound', { id: '123' });
+const ko = generateFailure(
+    'processError',
+    'notFound',
+    { id: '123' },
+    'userService', // issuer (optional)
+    'Utilisateur non trouvé.', // localizedMessage (optional)
+);
 ```
 
 ### Compose (sync)
@@ -100,13 +108,33 @@ import { generateMessage } from '@gilles-coudert/pure-trace';
 
 const traced = parseAge('25').tap((r) => {
     r.addTraces(
-        generateMessage('information', 'information', 'ageParsed', {
-            input: '25',
-        }),
+        generateMessage(
+            'information',
+            'information',
+            'ageParsed',
+            { input: '25' },
+            'userService', // issuer (optional)
+            'Âge analysé avec succès.', // localizedMessage (optional)
+        ),
     );
 });
 ```
 
+### Enrich error messages
+
+You can add issuer to errors and traces:
+
+```ts
+import { generateError } from '@gilles-coudert/pure-trace';
+
+const error = generateError({
+    type: 'processError',
+    code: 'invalidAgeFormat',
+    data: { input: 'abc' },
+    issuer: 'userService', // optional
+});
+```
+
 ### Async flows
 
 ```ts
@@ -138,6 +166,21 @@ generateFailure('processError', 'userNotFound', { userId: '123' });
 // fr: "L'utilisateur {userId} n'a pas été trouvé"
 ```
 
+Sometimes, translations have to be done at the source.
+In these cases, the localized message can be specified directly.
+
+```ts
+import { generateError } from '@gilles-coudert/pure-trace';
+
+const error = generateError({
+    type: 'processError',
+    code: 'invalidAgeFormat',
+    data: { input: 'abc' },
+    issuer: 'userService', // optional
+    localizedMessage: "L'âge indiqué est incorrect.",
+});
+```
+
 ## What makes PureTrace different?
 
 - Traces propagate automatically with the Result

package/lib/pure_message.d.ts

@@ -4,48 +4,56 @@ export declare const messageSchema: z.ZodObject<{
     type: z.ZodString;
     code: z.ZodString;
     data: z.ZodOptional<z.ZodJSONSchema>;
+    issuer: z.ZodOptional<z.ZodString>;
+    localizedMessage: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type Message = z.infer<typeof messageSchema>;
 export declare const errorSchema: z.ZodObject<{
     type: z.ZodString;
     code: z.ZodString;
     data: z.ZodOptional<z.ZodJSONSchema>;
+    issuer: z.ZodOptional<z.ZodString>;
+    localizedMessage: z.ZodOptional<z.ZodString>;
     kind: z.ZodLiteral<"error">;
 }, z.core.$strip>;
 export type Error = z.infer<typeof errorSchema>;
-declare const nativeErrorDefinitions: {
+type NativeErrorDefinitions = {
     readonly pureTraceInternalError: z.ZodObject<{
-        message: z.ZodObject<{}, z.core.$loose>;
-        zodError: z.ZodObject<{}, z.core.$loose>;
+        message: z.ZodObject<z.core.$ZodLooseShape, z.core.$loose>;
+        zodError: z.ZodObject<z.core.$ZodLooseShape, z.core.$loose>;
     }, z.core.$strip>;
     readonly technicalIssue: z.ZodJSONSchema;
     readonly processError: z.ZodJSONSchema;
 };
-type NativeErrorDefinitions = typeof nativeErrorDefinitions;
 export type NativeErrorType = keyof NativeErrorDefinitions;
-export type NativeErrorData<T extends NativeErrorType> = z.infer<(typeof nativeErrorDefinitions)[T]>;
-export declare function generateError<T extends NativeErrorType>(type: T, code: string, data?: NativeErrorData<T>): Error;
-declare const nativeMessageDefinitions: {
-    readonly error: {
-        readonly pureTraceInternalError: z.ZodObject<{
-            message: z.ZodObject<{}, z.core.$loose>;
-            zodError: z.ZodObject<{}, z.core.$loose>;
-        }, z.core.$strip>;
-        readonly technicalIssue: z.ZodJSONSchema;
-        readonly processError: z.ZodJSONSchema;
+export type NativeErrorData<T extends NativeErrorType> = z.infer<NativeErrorDefinitions[T]>;
+export declare function generateError<T extends NativeErrorType>(options: {
+    type: T;
+    code: string;
+    data?: NativeErrorData<T>;
+    issuer?: string;
+    localizedMessage?: string;
+}): Error;
+type NativeMessageDefinitions = {
+    error: NativeErrorDefinitions;
+    information: {
+        warning: z.ZodJSONSchema;
+        information: z.ZodJSONSchema;
     };
-    readonly information: {
-        readonly warning: z.ZodJSONSchema;
-        readonly information: z.ZodJSONSchema;
-    };
-    readonly metric: {
-        readonly start: z.ZodISODateTime;
-        readonly stop: z.ZodISODateTime;
+    metric: {
+        start: z.ZodISODateTime;
+        stop: z.ZodISODateTime;
     };
 };
-type NativeMessageDefinitions = typeof nativeMessageDefinitions;
 type NativeMessageKind = keyof NativeMessageDefinitions;
 type NativeMessageType<K extends NativeMessageKind> = keyof NativeMessageDefinitions[K];
 type NativeMessageData<K extends NativeMessageKind, T extends NativeMessageType<K>> = NativeMessageDefinitions[K][T];
-export declare function generateMessage<K extends NativeMessageKind, T extends NativeMessageType<K>>(kind: K, type: T, code: string, data?: NativeMessageData<K, T>): Message;
+export declare function generateMessage<K extends NativeMessageKind, T extends NativeMessageType<K>>(options: {
+    kind: K;
+    type: T;
+    code: string;
+    data?: NativeMessageData<K, T>;
+    issuer?: string;
+    localizedMessage?: string;
+}): Message;
 export {};

package/lib/pure_message.js

@@ -12,42 +12,20 @@ exports.messageSchema = zod_1.default.object({
     type: zod_1.default.string(),
     code: zod_1.default.string(),
     data: zod_1.default.json().optional(),
+    issuer: zod_1.default.string().min(1).optional(),
+    localizedMessage: zod_1.default.string().min(1).optional(),
 });
 exports.errorSchema = exports.messageSchema.extend({
     kind: zod_1.default.literal('error'),
 });
-const nativeErrorDefinitions = {
-    pureTraceInternalError: zod_1.default.object({
-        message: zod_1.default.looseObject({}),
-        zodError: zod_1.default.looseObject({}),
-    }),
-    technicalIssue: zod_1.default.json(),
-    processError: zod_1.default.json(),
-};
-function generateError(type, code, data) {
+function generateError(options) {
     return {
         kind: 'error',
-        type,
-        code,
-        data,
+        ...options,
     };
 }
-const nativeMessageDefinitions = {
-    error: nativeErrorDefinitions,
-    information: {
-        warning: zod_1.default.json(),
-        information: zod_1.default.json(),
-    },
-    metric: {
-        start: zod_1.default.iso.datetime(),
-        stop: zod_1.default.iso.datetime(),
-    },
-};
-function generateMessage(kind, type, code, data) {
+function generateMessage(options) {
     return {
-        kind,
-        type,
-        code,
-        data,
+        ...options,
     };
 }

package/lib/pure_result.d.ts

@@ -23,12 +23,12 @@ export declare class Success<S> extends PureResult<S> {
     isSuccess(): this is Success<S>;
     isFailure(): this is Failure;
     mapSuccess<S2>(f: (value: S) => Success<S2>): Result<S2>;
-    mapFailure(f: (errors: Message[]) => Failure): Result<S>;
-    mapBoth<S2>(onSuccess: (value: S) => Success<S2>, onFailure: (errors: Message[]) => Failure): Result<S2>;
+    mapFailure(_: (errors: Message[]) => Failure): Result<S>;
+    mapBoth<S2>(onSuccess: (value: S) => Success<S2>, _: (errors: Message[]) => Failure): Result<S2>;
     chainSuccess<S2>(f: (value: S) => Result<S2>): Result<S2>;
-    chainFailure<S2>(f: (errors: Message[]) => Result<S2>): Result<S | S2>;
-    chainBoth<S2, S3>(onSuccess: (value: S) => Result<S2>, onFailure: (errors: Message[]) => Result<S3>): Result<S2 | S3>;
-    convertFailureToSuccess(defaultValue: S): Success<S>;
+    chainFailure<S2>(_: (errors: Message[]) => Result<S2>): Result<S | S2>;
+    chainBoth<S2, S3>(onSuccess: (value: S) => Result<S2>, _: (errors: Message[]) => Result<S3>): Result<S2 | S3>;
+    convertFailureToSuccess(_: S): Success<S>;
 }
 export declare class Failure extends PureResult<never> {
     private readonly errors;
@@ -37,15 +37,15 @@ export declare class Failure extends PureResult<never> {
     addErrors(errors: Error[]): this;
     isSuccess(): this is Success<never>;
     isFailure(): this is Failure;
-    mapSuccess<S2>(f: (value: never) => Success<S2>): Result<S2>;
+    mapSuccess<S2>(_: (value: never) => Success<S2>): Result<S2>;
     mapFailure(f: (errors: Message[]) => Failure): Result<never>;
-    mapBoth<S2>(onSuccess: (value: never) => Success<S2>, onFailure: (errors: Message[]) => Failure): Result<S2>;
-    chainSuccess<S2>(f: (value: never) => Result<S2>): Result<S2>;
-    chainFailure<S2>(f: (errors: Message[]) => Result<S2>): Result<never | S2>;
-    chainBoth<S2, S3>(onSuccess: (value: never) => Result<S2>, onFailure: (errors: Message[]) => Result<S3>): Result<S2 | S3>;
+    mapBoth<S2>(_: (value: never) => Success<S2>, onFailure: (errors: Message[]) => Failure): Result<S2>;
+    chainSuccess<S2>(_: (value: never) => Result<S2>): Result<S2>;
+    chainFailure<S2>(f: (errors: Message[]) => Result<S2>): Result<S2>;
+    chainBoth<S2, S3>(_: (value: never) => Result<S2>, onFailure: (errors: Message[]) => Result<S3>): Result<S2 | S3>;
     convertFailureToSuccess(defaultValue: never): Success<never>;
 }
-export declare function generateFailure<T extends NativeErrorType>(type: T, code: string, data: NativeErrorData<T>): Failure;
+export declare function generateFailure<T extends NativeErrorType>(type: T, code: string, data: NativeErrorData<T>, issuer?: string, localizedMessage?: string): Failure;
 export declare class GetResult {
     static fromThrowable<X>(functionToAudit: () => X, onFailure: (catchedError: unknown) => Failure): Result<X>;
     static fromResultArray<X>(results: Result<X>[], firstFailureOnly?: boolean): Result<X[]>;

package/lib/pure_result.js

@@ -21,9 +21,13 @@ class PureResult {
         for (let trace of traces) {
             const zodParseResult = pure_message_1.messageSchema.safeParse(trace);
             if (!zodParseResult.success) {
-                trace = (0, pure_message_1.generateError)('pureTraceInternalError', 'invalidTraceMessage', {
-                    message: trace,
-                    zodError: zod_1.default.treeifyError(zodParseResult.error),
+                trace = (0, pure_message_1.generateError)({
+                    type: 'pureTraceInternalError',
+                    code: 'invalidTraceMessage',
+                    data: {
+                        message: trace,
+                        zodError: zod_1.default.treeifyError(zodParseResult.error),
+                    },
                 });
             }
             this.traces.push(trace);
@@ -53,22 +57,22 @@ class Success extends PureResult {
     mapSuccess(f) {
         return f(this.value).addTraces(...this.getTraces());
     }
-    mapFailure(f) {
+    mapFailure(_) {
         return this;
     }
-    mapBoth(onSuccess, onFailure) {
+    mapBoth(onSuccess, _) {
         return this.mapSuccess(onSuccess);
     }
     chainSuccess(f) {
         return f(this.value).addTraces(...this.getTraces());
     }
-    chainFailure(f) {
+    chainFailure(_) {
         return this;
     }
-    chainBoth(onSuccess, onFailure) {
+    chainBoth(onSuccess, _) {
         return this.chainSuccess(onSuccess);
     }
-    convertFailureToSuccess(defaultValue) {
+    convertFailureToSuccess(_) {
         return this;
     }
 }
@@ -86,9 +90,13 @@ class Failure extends PureResult {
         for (let error of errors) {
             const zodParseResult = pure_message_1.messageSchema.safeParse(error);
             if (!zodParseResult.success) {
-                error = (0, pure_message_1.generateError)('pureTraceInternalError', 'invalidError', {
-                    message: error,
-                    zodError: zod_1.default.treeifyError(zodParseResult.error),
+                error = (0, pure_message_1.generateError)({
+                    type: 'pureTraceInternalError',
+                    code: 'invalidError',
+                    data: {
+                        message: error,
+                        zodError: zod_1.default.treeifyError(zodParseResult.error),
+                    },
                 });
             }
             this.errors.push(error);
@@ -101,22 +109,22 @@ class Failure extends PureResult {
     isFailure() {
         return true;
     }
-    mapSuccess(f) {
+    mapSuccess(_) {
         return this;
     }
     mapFailure(f) {
         return f(this.getErrors()).addTraces(...this.getTraces());
     }
-    mapBoth(onSuccess, onFailure) {
+    mapBoth(_, onFailure) {
         return this.mapFailure(onFailure);
     }
-    chainSuccess(f) {
+    chainSuccess(_) {
         return this;
     }
     chainFailure(f) {
         return f(this.getErrors()).addTraces(...this.getTraces());
     }
-    chainBoth(onSuccess, onFailure) {
+    chainBoth(_, onFailure) {
         return this.chainFailure(onFailure);
     }
     convertFailureToSuccess(defaultValue) {
@@ -124,8 +132,14 @@ class Failure extends PureResult {
     }
 }
 exports.Failure = Failure;
-function generateFailure(type, code, data) {
-    return new Failure((0, pure_message_1.generateError)(type, code, data));
+function generateFailure(type, code, data, issuer, localizedMessage) {
+    return new Failure((0, pure_message_1.generateError)({
+        type,
+        code,
+        data,
+        issuer,
+        localizedMessage,
+    }));
 }
 class GetResult {
     static fromThrowable(functionToAudit, onFailure) {

package/lib/pure_result_async.d.ts

@@ -1,13 +1,13 @@
 import { Message } from './pure_message';
 import { Success, Failure, Result } from './pure_result';
-type ResultAsyncValue<S> = PromiseLike<Success<S>>;
-interface ResultAsyncHelpers {
+export type ResultAsyncValue<S> = PromiseLike<Success<S>>;
+export interface ResultAsyncHelpers {
     liftResult<S>(result: Result<S>): ResultAsyncValue<S>;
     liftSuccess<S>(value: S): ResultAsyncValue<S>;
     fromResultPromise<S>(promise: PromiseLike<Result<S>>): ResultAsyncValue<S>;
     fromPromise<S>(promise: PromiseLike<S>, failure: (reason: unknown) => Failure): ResultAsyncValue<S>;
 }
-interface ResultAsync<S> extends PromiseLike<Result<S>> {
+export interface ResultAsync<S> extends PromiseLike<Result<S>> {
     resolve(): Promise<Result<S>>;
     tap(f: (result: Result<S>) => void): ResultAsync<S>;
     mapSuccess<S2>(onSuccess: (value: S) => Success<S2>): ResultAsync<S2>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gilles-coudert/pure-trace",
-    "version": "1.0.5",
+    "version": "1.0.7",
     "description": "A TypeScript library providing standardized, localizable, and traceable error handling by design, with observability built-in.",
     "private": false,
     "publishConfig": {
@@ -14,7 +14,8 @@
     "scripts": {
         "prebuild": "node -e \"require('fs').rmSync('lib', { recursive: true, force: true })\"",
         "build": "tsc",
-        "test": "jest --runInBand"
+        "test": "jest --runInBand",
+        "lint": "eslint src/**/*.ts"
     },
     "repository": {
         "type": "git",
@@ -45,6 +46,7 @@
         "globals": "^17.3.0",
         "jest": "^30.2.0",
         "jest-cucumber": "^4.5.0",
+        "jiti": "^2.6.1",
         "prettier": "^3.8.1",
         "ts-jest": "^29.4.6",
         "typescript": "^5.9.3",