@noego/trust 0.3.0 → 0.5.0-dev.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -4,9 +4,15 @@
4
4
  * `Result<T, E>` is `Ok<T> | Err<E>`, discriminated by `ok`. This module has no
5
5
  * imports so it is safe in any bundle (Node, Electron main, renderer, browser).
6
6
  *
7
- * The `@noego/trust/eslint` rules recognise these declarations by identity (not by
8
- * name): a call whose declared return type is a `Result` from this module is
9
- * trusted, and a `catch` is accepted when it returns an `Err` from this module.
7
+ * Public surface is two namespaces:
8
+ *
9
+ * Result.ok / Result.err — make a result
10
+ * Trust.try / Trust.tryAsync — the only boundary that may catch a throw
11
+ * Trust.decide / Trust.translate — the only places a failure may stop or change
12
+ *
13
+ * The underlying functions are exported as well because the `@noego/trust/eslint`
14
+ * rules recognise calls by their declaration (not by name): `Trust.try(...)` resolves
15
+ * to `tryResult`, `Result.err(...)` to `err`. Write the namespace form in application code.
10
16
  */
11
17
  type Ok<T> = {
12
18
  readonly ok: true;
@@ -16,16 +22,20 @@ type Err<E> = {
16
22
  readonly ok: false;
17
23
  readonly error: E;
18
24
  };
25
+ /** A failure is an object with a literal `kind` plus any fields. */
26
+ type Failure<K extends string = string, Fields extends object = {}> = {
27
+ readonly kind: K;
28
+ } & Readonly<Fields>;
19
29
  /** Wraps a success value. */
20
30
  declare function ok<T>(value: T): Ok<T>;
21
31
  /**
22
32
  * Wraps a failure value. Pass a typed error, not a raw caught value.
23
33
  *
24
34
  * The first overload keeps a literal `kind` for inline failures (`err({ kind: 'X' })`
25
- * gives `Err<{ kind: 'X' }>`) through the `K` hint in the intersection. `E` itself is
26
- * still a plain type parameter, so a declared `Result` return type sets it and other
27
- * literal fields keep their declared union types. The second overload covers
28
- * arguments that cannot meet the intersection (generic, unknown, null, undefined).
35
+ * gives `Err<{ kind: 'X' }>`) through the `K` hint in the intersection, so no `as const`
36
+ * is needed. `E` itself is still a plain type parameter, so a declared `Result` return
37
+ * type sets it and other literal fields keep their declared union types. The second
38
+ * overload covers arguments that cannot meet the intersection (generic, unknown, null).
29
39
  */
30
40
  declare function err<E, K extends string = string>(error: E & {
31
41
  readonly kind?: K;
@@ -47,14 +57,22 @@ declare function tryResultAsync<T, E, K extends string = string>(fn: () => T | P
47
57
  readonly kind?: K;
48
58
  }): Promise<Result<T, E>>;
49
59
  declare function tryResultAsync<T, E>(fn: () => T | PromiseLike<T>, onError: (cause: unknown) => E): Promise<Result<T, E>>;
50
- /** A failure is an object with a literal `kind` plus any fields. */
51
- type Failure<K extends string = string, Fields extends object = {}> = {
60
+ type IsUnion<T, U = T> = T extends unknown ? ([U] extends [T] ? false : true) : never;
61
+ /**
62
+ * One failure per kind. A single declared failure whose `kind` is a union
63
+ * (`{ kind: 'a' | 'b'; op: string }`) is split into `{...; kind: 'a'} | {...; kind: 'b'}`
64
+ * so that handlers narrow to one kind each; failures that already have one
65
+ * literal kind are left as they are.
66
+ */
67
+ type SplitByKind<E> = E extends {
68
+ readonly kind: infer K extends string;
69
+ } ? IsUnion<K> extends true ? K extends unknown ? E & {
52
70
  readonly kind: K;
53
- } & Readonly<Fields>;
71
+ } : never : E : never;
54
72
  type KindsOf<E> = E extends {
55
73
  readonly kind: infer K extends string;
56
74
  } ? K : never;
57
- type ErrorOf<R> = R extends Err<infer E> ? E : never;
75
+ type ErrorOf<R> = R extends Err<infer E> ? SplitByKind<E> : never;
58
76
  type OkOf<R> = R extends Ok<infer T> ? T : never;
59
77
  type CannotFail = {
60
78
  readonly __trust: 'decide needs a result that can fail (it has no Err member)';
@@ -65,7 +83,8 @@ type BadFailure = {
65
83
  type NeedsLiteralKind = {
66
84
  readonly __trust: 'a translate mapper must return an object with a literal string kind';
67
85
  };
68
- type FailureGuard<R> = [ErrorOf<R>] extends [never] ? CannotFail : [ErrorOf<R>] extends [{
86
+ type RawErrorOf<R> = R extends Err<infer E> ? E : never;
87
+ type FailureGuard<R> = [RawErrorOf<R>] extends [never] ? CannotFail : [RawErrorOf<R>] extends [{
69
88
  readonly kind: string;
70
89
  }] ? unknown : BadFailure;
71
90
  type HandlerBase<E, H> = {
@@ -101,20 +120,28 @@ type Decided<R, H> = [Remaining<ErrorOf<R>, H>] extends [never] ? Ok<OkOf<R> | H
101
120
  type Translated<R, M> = Ok<OkOf<R>> | Err<M[keyof M] | Remaining<ErrorOf<R>, M>>;
102
121
  /**
103
122
  * The only place a failure may stop: a failure whose kind has a handler becomes
104
- * `ok(handler(failure))`; anything else is returned untouched. Handlers are synchronous.
123
+ * `ok(handler(failure))`; anything else is returned untouched. Handlers are synchronous
124
+ * and must return a value (never `undefined`/`void`).
105
125
  */
106
126
  declare function decide<R extends Result<unknown, unknown>, H extends HandlerBase<ErrorOf<R>, H>>(result: R & FailureGuard<R>, handlers: HandlerFns<ErrorOf<R>, H>): Decided<R, H>;
107
127
  /** Turns failures into different failures; unmapped failures and successes pass through untouched. */
108
128
  declare function translate<R extends Result<unknown, unknown>, M extends MapperBase<ErrorOf<R>, M>>(result: R & FailureGuard<R>, mappers: MapperFns<ErrorOf<R>, M>, ...check: KindCheck<M>): Translated<R, M>;
109
129
  type Result<T, E> = Ok<T> | Err<E>;
110
- /** Namespace form: `Result.ok`, `Result.err`, `Result.try`, `Result.tryAsync`, `Result.decide`, `Result.translate`. */
130
+ /** Make a result: `Result.ok(value)`, `Result.err({ kind: 'x', ... })`. */
111
131
  declare const Result: {
112
132
  readonly ok: typeof ok;
113
133
  readonly err: typeof err;
134
+ };
135
+ /**
136
+ * Apply the discipline:
137
+ * `Trust.try` / `Trust.tryAsync` are the only boundary that may catch a throw;
138
+ * `Trust.decide` is the only place a failure may stop; `Trust.translate` the only place it may change kind.
139
+ */
140
+ declare const Trust: {
114
141
  readonly try: typeof tryResult;
115
142
  readonly tryAsync: typeof tryResultAsync;
116
143
  readonly decide: typeof decide;
117
144
  readonly translate: typeof translate;
118
145
  };
119
146
 
120
- export { type Err, type Failure, type Ok, Result, decide, err, ok, translate, tryResult, tryResultAsync };
147
+ export { type Err, type Failure, type Ok, Result, Trust, decide, err, ok, translate, tryResult, tryResultAsync };
package/dist/index.d.ts CHANGED
@@ -4,9 +4,15 @@
4
4
  * `Result<T, E>` is `Ok<T> | Err<E>`, discriminated by `ok`. This module has no
5
5
  * imports so it is safe in any bundle (Node, Electron main, renderer, browser).
6
6
  *
7
- * The `@noego/trust/eslint` rules recognise these declarations by identity (not by
8
- * name): a call whose declared return type is a `Result` from this module is
9
- * trusted, and a `catch` is accepted when it returns an `Err` from this module.
7
+ * Public surface is two namespaces:
8
+ *
9
+ * Result.ok / Result.err — make a result
10
+ * Trust.try / Trust.tryAsync — the only boundary that may catch a throw
11
+ * Trust.decide / Trust.translate — the only places a failure may stop or change
12
+ *
13
+ * The underlying functions are exported as well because the `@noego/trust/eslint`
14
+ * rules recognise calls by their declaration (not by name): `Trust.try(...)` resolves
15
+ * to `tryResult`, `Result.err(...)` to `err`. Write the namespace form in application code.
10
16
  */
11
17
  type Ok<T> = {
12
18
  readonly ok: true;
@@ -16,16 +22,20 @@ type Err<E> = {
16
22
  readonly ok: false;
17
23
  readonly error: E;
18
24
  };
25
+ /** A failure is an object with a literal `kind` plus any fields. */
26
+ type Failure<K extends string = string, Fields extends object = {}> = {
27
+ readonly kind: K;
28
+ } & Readonly<Fields>;
19
29
  /** Wraps a success value. */
20
30
  declare function ok<T>(value: T): Ok<T>;
21
31
  /**
22
32
  * Wraps a failure value. Pass a typed error, not a raw caught value.
23
33
  *
24
34
  * The first overload keeps a literal `kind` for inline failures (`err({ kind: 'X' })`
25
- * gives `Err<{ kind: 'X' }>`) through the `K` hint in the intersection. `E` itself is
26
- * still a plain type parameter, so a declared `Result` return type sets it and other
27
- * literal fields keep their declared union types. The second overload covers
28
- * arguments that cannot meet the intersection (generic, unknown, null, undefined).
35
+ * gives `Err<{ kind: 'X' }>`) through the `K` hint in the intersection, so no `as const`
36
+ * is needed. `E` itself is still a plain type parameter, so a declared `Result` return
37
+ * type sets it and other literal fields keep their declared union types. The second
38
+ * overload covers arguments that cannot meet the intersection (generic, unknown, null).
29
39
  */
30
40
  declare function err<E, K extends string = string>(error: E & {
31
41
  readonly kind?: K;
@@ -47,14 +57,22 @@ declare function tryResultAsync<T, E, K extends string = string>(fn: () => T | P
47
57
  readonly kind?: K;
48
58
  }): Promise<Result<T, E>>;
49
59
  declare function tryResultAsync<T, E>(fn: () => T | PromiseLike<T>, onError: (cause: unknown) => E): Promise<Result<T, E>>;
50
- /** A failure is an object with a literal `kind` plus any fields. */
51
- type Failure<K extends string = string, Fields extends object = {}> = {
60
+ type IsUnion<T, U = T> = T extends unknown ? ([U] extends [T] ? false : true) : never;
61
+ /**
62
+ * One failure per kind. A single declared failure whose `kind` is a union
63
+ * (`{ kind: 'a' | 'b'; op: string }`) is split into `{...; kind: 'a'} | {...; kind: 'b'}`
64
+ * so that handlers narrow to one kind each; failures that already have one
65
+ * literal kind are left as they are.
66
+ */
67
+ type SplitByKind<E> = E extends {
68
+ readonly kind: infer K extends string;
69
+ } ? IsUnion<K> extends true ? K extends unknown ? E & {
52
70
  readonly kind: K;
53
- } & Readonly<Fields>;
71
+ } : never : E : never;
54
72
  type KindsOf<E> = E extends {
55
73
  readonly kind: infer K extends string;
56
74
  } ? K : never;
57
- type ErrorOf<R> = R extends Err<infer E> ? E : never;
75
+ type ErrorOf<R> = R extends Err<infer E> ? SplitByKind<E> : never;
58
76
  type OkOf<R> = R extends Ok<infer T> ? T : never;
59
77
  type CannotFail = {
60
78
  readonly __trust: 'decide needs a result that can fail (it has no Err member)';
@@ -65,7 +83,8 @@ type BadFailure = {
65
83
  type NeedsLiteralKind = {
66
84
  readonly __trust: 'a translate mapper must return an object with a literal string kind';
67
85
  };
68
- type FailureGuard<R> = [ErrorOf<R>] extends [never] ? CannotFail : [ErrorOf<R>] extends [{
86
+ type RawErrorOf<R> = R extends Err<infer E> ? E : never;
87
+ type FailureGuard<R> = [RawErrorOf<R>] extends [never] ? CannotFail : [RawErrorOf<R>] extends [{
69
88
  readonly kind: string;
70
89
  }] ? unknown : BadFailure;
71
90
  type HandlerBase<E, H> = {
@@ -101,20 +120,28 @@ type Decided<R, H> = [Remaining<ErrorOf<R>, H>] extends [never] ? Ok<OkOf<R> | H
101
120
  type Translated<R, M> = Ok<OkOf<R>> | Err<M[keyof M] | Remaining<ErrorOf<R>, M>>;
102
121
  /**
103
122
  * The only place a failure may stop: a failure whose kind has a handler becomes
104
- * `ok(handler(failure))`; anything else is returned untouched. Handlers are synchronous.
123
+ * `ok(handler(failure))`; anything else is returned untouched. Handlers are synchronous
124
+ * and must return a value (never `undefined`/`void`).
105
125
  */
106
126
  declare function decide<R extends Result<unknown, unknown>, H extends HandlerBase<ErrorOf<R>, H>>(result: R & FailureGuard<R>, handlers: HandlerFns<ErrorOf<R>, H>): Decided<R, H>;
107
127
  /** Turns failures into different failures; unmapped failures and successes pass through untouched. */
108
128
  declare function translate<R extends Result<unknown, unknown>, M extends MapperBase<ErrorOf<R>, M>>(result: R & FailureGuard<R>, mappers: MapperFns<ErrorOf<R>, M>, ...check: KindCheck<M>): Translated<R, M>;
109
129
  type Result<T, E> = Ok<T> | Err<E>;
110
- /** Namespace form: `Result.ok`, `Result.err`, `Result.try`, `Result.tryAsync`, `Result.decide`, `Result.translate`. */
130
+ /** Make a result: `Result.ok(value)`, `Result.err({ kind: 'x', ... })`. */
111
131
  declare const Result: {
112
132
  readonly ok: typeof ok;
113
133
  readonly err: typeof err;
134
+ };
135
+ /**
136
+ * Apply the discipline:
137
+ * `Trust.try` / `Trust.tryAsync` are the only boundary that may catch a throw;
138
+ * `Trust.decide` is the only place a failure may stop; `Trust.translate` the only place it may change kind.
139
+ */
140
+ declare const Trust: {
114
141
  readonly try: typeof tryResult;
115
142
  readonly tryAsync: typeof tryResultAsync;
116
143
  readonly decide: typeof decide;
117
144
  readonly translate: typeof translate;
118
145
  };
119
146
 
120
- export { type Err, type Failure, type Ok, Result, decide, err, ok, translate, tryResult, tryResultAsync };
147
+ export { type Err, type Failure, type Ok, Result, Trust, decide, err, ok, translate, tryResult, tryResultAsync };
package/dist/index.js CHANGED
@@ -33,9 +33,11 @@ function translate(result, mappers) {
33
33
  const mapper = pick(mappers, result.error?.kind);
34
34
  return mapper === void 0 ? result : err(mapper(result.error));
35
35
  }
36
- var Result = { ok, err, try: tryResult, tryAsync: tryResultAsync, decide, translate };
36
+ var Result = { ok, err };
37
+ var Trust = { try: tryResult, tryAsync: tryResultAsync, decide, translate };
37
38
  export {
38
39
  Result,
40
+ Trust,
39
41
  decide,
40
42
  err,
41
43
  ok,
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * Closed result primitive: expected failures are values, not exceptions.\n *\n * `Result<T, E>` is `Ok<T> | Err<E>`, discriminated by `ok`. This module has no\n * imports so it is safe in any bundle (Node, Electron main, renderer, browser).\n *\n * The `@noego/trust/eslint` rules recognise these declarations by identity (not by\n * name): a call whose declared return type is a `Result` from this module is\n * trusted, and a `catch` is accepted when it returns an `Err` from this module.\n */\nexport type Ok<T> = { readonly ok: true; readonly value: T };\nexport type Err<E> = { readonly ok: false; readonly error: E };\nexport type Result<T, E> = Ok<T> | Err<E>;\n\n/** Wraps a success value. */\nexport function ok<T>(value: T): Ok<T> {\n return { ok: true, value };\n}\n\n/**\n * Wraps a failure value. Pass a typed error, not a raw caught value.\n *\n * The first overload keeps a literal `kind` for inline failures (`err({ kind: 'X' })`\n * gives `Err<{ kind: 'X' }>`) through the `K` hint in the intersection. `E` itself is\n * still a plain type parameter, so a declared `Result` return type sets it and other\n * literal fields keep their declared union types. The second overload covers\n * arguments that cannot meet the intersection (generic, unknown, null, undefined).\n */\nexport function err<E, K extends string = string>(error: E & { readonly kind?: K }): Err<E>;\nexport function err<E>(error: E): Err<E>;\nexport function err<E>(error: E): Err<E> {\n return { ok: false, error };\n}\n\n/**\n * Runs `fn` and converts anything it throws into `Err` via `onError`.\n * Calls made directly inside `fn` count as guarded for the trust lint rules.\n */\nexport function tryResult<T, E, K extends string = string>(\n fn: () => T,\n onError: (cause: unknown) => E & { readonly kind?: K },\n): Result<T, E>;\nexport function tryResult<T, E>(fn: () => T, onError: (cause: unknown) => E): Result<T, E>;\nexport function tryResult<T, E>(fn: () => T, onError: (cause: unknown) => E): Result<T, E> {\n try {\n return ok(fn());\n } catch (cause) {\n return err(onError(cause));\n }\n}\n\n/**\n * Awaits `fn` and converts a throw or rejection into `Err` via `onError`.\n * Calls made directly inside `fn` count as guarded for the trust lint rules.\n */\nexport function tryResultAsync<T, E, K extends string = string>(\n fn: () => T | PromiseLike<T>,\n onError: (cause: unknown) => E & { readonly kind?: K },\n): Promise<Result<T, E>>;\nexport function tryResultAsync<T, E>(\n fn: () => T | PromiseLike<T>,\n onError: (cause: unknown) => E,\n): Promise<Result<T, E>>;\nexport async function tryResultAsync<T, E>(\n fn: () => T | PromiseLike<T>,\n onError: (cause: unknown) => E,\n): Promise<Result<T, E>> {\n try {\n return ok(await fn());\n } catch (cause) {\n return err(onError(cause));\n }\n}\n\n/** A failure is an object with a literal `kind` plus any fields. */\nexport type Failure<K extends string = string, Fields extends object = {}> = { readonly kind: K } & Readonly<Fields>;\n\ntype KindsOf<E> = E extends { readonly kind: infer K extends string } ? K : never;\ntype ErrorOf<R> = R extends Err<infer E> ? E : never;\ntype OkOf<R> = R extends Ok<infer T> ? T : never;\ntype CannotFail = { readonly __trust: 'decide needs a result that can fail (it has no Err member)' };\ntype BadFailure = { readonly __trust: 'every failure needs a string `kind` (string and Error are not failures)' };\ntype NeedsLiteralKind = { readonly __trust: 'a translate mapper must return an object with a literal string kind' };\n\ntype FailureGuard<R> = [ErrorOf<R>] extends [never]\n ? CannotFail\n : [ErrorOf<R>] extends [{ readonly kind: string }]\n ? unknown\n : BadFailure;\n\ntype HandlerBase<E, H> = { [K in keyof H]: K extends KindsOf<E> ? {} | null : never };\ntype HandlerFns<E, H> = {\n [K in keyof H]-?: (failure: Extract<E, { readonly kind: K }>) => H[K];\n};\ntype LiteralKind = '' | (string & {});\ntype MapperBase<E, M> = { [K in keyof M]: K extends KindsOf<E> ? { readonly kind: LiteralKind } : never };\ntype MapperFns<E, M> = {\n [K in keyof M]-?: (failure: Extract<E, { readonly kind: K }>) => M[K];\n};\ntype KindCheck<M> = [\n { [K in keyof M]-?: M[K] extends { readonly kind: infer Kd } ? (string extends Kd ? 1 : never) : 1 }[keyof M],\n] extends [never]\n ? []\n : [problem: NeedsLiteralKind];\n\ntype Remaining<E, H> = Exclude<E, { readonly kind: keyof H & string }>;\ntype Decided<R, H> = [Remaining<ErrorOf<R>, H>] extends [never]\n ? Ok<OkOf<R> | H[keyof H]>\n : Ok<OkOf<R> | H[keyof H]> | Err<Remaining<ErrorOf<R>, H>>;\ntype Translated<R, M> = Ok<OkOf<R>> | Err<M[keyof M] | Remaining<ErrorOf<R>, M>>;\n\nfunction pick(table: object, kind: unknown): ((failure: unknown) => unknown) | undefined {\n if (typeof kind !== 'string' || !Object.prototype.hasOwnProperty.call(table, kind)) return undefined;\n return (table as Record<string, (failure: unknown) => unknown>)[kind];\n}\n\n/**\n * The only place a failure may stop: a failure whose kind has a handler becomes\n * `ok(handler(failure))`; anything else is returned untouched. Handlers are synchronous.\n */\nexport function decide<R extends Result<unknown, unknown>, H extends HandlerBase<ErrorOf<R>, H>>(\n result: R & FailureGuard<R>,\n handlers: HandlerFns<ErrorOf<R>, H>,\n): Decided<R, H>;\nexport function decide(result: Result<unknown, unknown>, handlers: object): unknown {\n if (result.ok) return result;\n const handler = pick(handlers, (result.error as { kind?: unknown } | null)?.kind);\n return handler === undefined ? result : ok(handler(result.error));\n}\n\n/** Turns failures into different failures; unmapped failures and successes pass through untouched. */\nexport function translate<R extends Result<unknown, unknown>, M extends MapperBase<ErrorOf<R>, M>>(\n result: R & FailureGuard<R>,\n mappers: MapperFns<ErrorOf<R>, M>,\n ...check: KindCheck<M>\n): Translated<R, M>;\nexport function translate(result: Result<unknown, unknown>, mappers: object): unknown {\n if (result.ok) return result;\n const mapper = pick(mappers, (result.error as { kind?: unknown } | null)?.kind);\n return mapper === undefined ? result : err(mapper(result.error));\n}\n\n/** Namespace form: `Result.ok`, `Result.err`, `Result.try`, `Result.tryAsync`, `Result.decide`, `Result.translate`. */\nexport const Result: {\n readonly ok: typeof ok;\n readonly err: typeof err;\n readonly try: typeof tryResult;\n readonly tryAsync: typeof tryResultAsync;\n readonly decide: typeof decide;\n readonly translate: typeof translate;\n} = { ok, err, try: tryResult, tryAsync: tryResultAsync, decide, translate };\n"],"mappings":";AAeO,SAAS,GAAM,OAAiB;AACrC,SAAO,EAAE,IAAI,MAAM,MAAM;AAC3B;AAaO,SAAS,IAAO,OAAkB;AACvC,SAAO,EAAE,IAAI,OAAO,MAAM;AAC5B;AAWO,SAAS,UAAgB,IAAa,SAA8C;AACzF,MAAI;AACF,WAAO,GAAG,GAAG,CAAC;AAAA,EAChB,SAAS,OAAO;AACd,WAAO,IAAI,QAAQ,KAAK,CAAC;AAAA,EAC3B;AACF;AAcA,eAAsB,eACpB,IACA,SACuB;AACvB,MAAI;AACF,WAAO,GAAG,MAAM,GAAG,CAAC;AAAA,EACtB,SAAS,OAAO;AACd,WAAO,IAAI,QAAQ,KAAK,CAAC;AAAA,EAC3B;AACF;AAuCA,SAAS,KAAK,OAAe,MAA4D;AACvF,MAAI,OAAO,SAAS,YAAY,CAAC,OAAO,UAAU,eAAe,KAAK,OAAO,IAAI,EAAG,QAAO;AAC3F,SAAQ,MAAwD,IAAI;AACtE;AAUO,SAAS,OAAO,QAAkC,UAA2B;AAClF,MAAI,OAAO,GAAI,QAAO;AACtB,QAAM,UAAU,KAAK,UAAW,OAAO,OAAqC,IAAI;AAChF,SAAO,YAAY,SAAY,SAAS,GAAG,QAAQ,OAAO,KAAK,CAAC;AAClE;AAQO,SAAS,UAAU,QAAkC,SAA0B;AACpF,MAAI,OAAO,GAAI,QAAO;AACtB,QAAM,SAAS,KAAK,SAAU,OAAO,OAAqC,IAAI;AAC9E,SAAO,WAAW,SAAY,SAAS,IAAI,OAAO,OAAO,KAAK,CAAC;AACjE;AAGO,IAAM,SAOT,EAAE,IAAI,KAAK,KAAK,WAAW,UAAU,gBAAgB,QAAQ,UAAU;","names":[]}
1
+ {"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * Closed result primitive: expected failures are values, not exceptions.\n *\n * `Result<T, E>` is `Ok<T> | Err<E>`, discriminated by `ok`. This module has no\n * imports so it is safe in any bundle (Node, Electron main, renderer, browser).\n *\n * Public surface is two namespaces:\n *\n * Result.ok / Result.err — make a result\n * Trust.try / Trust.tryAsync — the only boundary that may catch a throw\n * Trust.decide / Trust.translate — the only places a failure may stop or change\n *\n * The underlying functions are exported as well because the `@noego/trust/eslint`\n * rules recognise calls by their declaration (not by name): `Trust.try(...)` resolves\n * to `tryResult`, `Result.err(...)` to `err`. Write the namespace form in application code.\n */\nexport type Ok<T> = { readonly ok: true; readonly value: T };\nexport type Err<E> = { readonly ok: false; readonly error: E };\nexport type Result<T, E> = Ok<T> | Err<E>;\n\n/** A failure is an object with a literal `kind` plus any fields. */\nexport type Failure<K extends string = string, Fields extends object = {}> = { readonly kind: K } & Readonly<Fields>;\n\n/** Wraps a success value. */\nexport function ok<T>(value: T): Ok<T> {\n return { ok: true, value };\n}\n\n/**\n * Wraps a failure value. Pass a typed error, not a raw caught value.\n *\n * The first overload keeps a literal `kind` for inline failures (`err({ kind: 'X' })`\n * gives `Err<{ kind: 'X' }>`) through the `K` hint in the intersection, so no `as const`\n * is needed. `E` itself is still a plain type parameter, so a declared `Result` return\n * type sets it and other literal fields keep their declared union types. The second\n * overload covers arguments that cannot meet the intersection (generic, unknown, null).\n */\nexport function err<E, K extends string = string>(error: E & { readonly kind?: K }): Err<E>;\nexport function err<E>(error: E): Err<E>;\nexport function err<E>(error: E): Err<E> {\n return { ok: false, error };\n}\n\n/**\n * Runs `fn` and converts anything it throws into `Err` via `onError`.\n * Calls made directly inside `fn` count as guarded for the trust lint rules.\n */\nexport function tryResult<T, E, K extends string = string>(\n fn: () => T,\n onError: (cause: unknown) => E & { readonly kind?: K },\n): Result<T, E>;\nexport function tryResult<T, E>(fn: () => T, onError: (cause: unknown) => E): Result<T, E>;\nexport function tryResult<T, E>(fn: () => T, onError: (cause: unknown) => E): Result<T, E> {\n try {\n return ok(fn());\n } catch (cause) {\n return err(onError(cause));\n }\n}\n\n/**\n * Awaits `fn` and converts a throw or rejection into `Err` via `onError`.\n * Calls made directly inside `fn` count as guarded for the trust lint rules.\n */\nexport function tryResultAsync<T, E, K extends string = string>(\n fn: () => T | PromiseLike<T>,\n onError: (cause: unknown) => E & { readonly kind?: K },\n): Promise<Result<T, E>>;\nexport function tryResultAsync<T, E>(\n fn: () => T | PromiseLike<T>,\n onError: (cause: unknown) => E,\n): Promise<Result<T, E>>;\nexport async function tryResultAsync<T, E>(\n fn: () => T | PromiseLike<T>,\n onError: (cause: unknown) => E,\n): Promise<Result<T, E>> {\n try {\n return ok(await fn());\n } catch (cause) {\n return err(onError(cause));\n }\n}\n\ntype IsUnion<T, U = T> = T extends unknown ? ([U] extends [T] ? false : true) : never;\n/**\n * One failure per kind. A single declared failure whose `kind` is a union\n * (`{ kind: 'a' | 'b'; op: string }`) is split into `{...; kind: 'a'} | {...; kind: 'b'}`\n * so that handlers narrow to one kind each; failures that already have one\n * literal kind are left as they are.\n */\ntype SplitByKind<E> = E extends { readonly kind: infer K extends string }\n ? IsUnion<K> extends true\n ? K extends unknown\n ? E & { readonly kind: K }\n : never\n : E\n : never;\n\ntype KindsOf<E> = E extends { readonly kind: infer K extends string } ? K : never;\ntype ErrorOf<R> = R extends Err<infer E> ? SplitByKind<E> : never;\ntype OkOf<R> = R extends Ok<infer T> ? T : never;\ntype CannotFail = { readonly __trust: 'decide needs a result that can fail (it has no Err member)' };\ntype BadFailure = { readonly __trust: 'every failure needs a string `kind` (string and Error are not failures)' };\ntype NeedsLiteralKind = { readonly __trust: 'a translate mapper must return an object with a literal string kind' };\n\ntype RawErrorOf<R> = R extends Err<infer E> ? E : never;\ntype FailureGuard<R> = [RawErrorOf<R>] extends [never]\n ? CannotFail\n : [RawErrorOf<R>] extends [{ readonly kind: string }]\n ? unknown\n : BadFailure;\n\ntype HandlerBase<E, H> = { [K in keyof H]: K extends KindsOf<E> ? {} | null : never };\ntype HandlerFns<E, H> = {\n [K in keyof H]-?: (failure: Extract<E, { readonly kind: K }>) => H[K];\n};\ntype LiteralKind = '' | (string & {});\ntype MapperBase<E, M> = { [K in keyof M]: K extends KindsOf<E> ? { readonly kind: LiteralKind } : never };\ntype MapperFns<E, M> = {\n [K in keyof M]-?: (failure: Extract<E, { readonly kind: K }>) => M[K];\n};\ntype KindCheck<M> = [\n { [K in keyof M]-?: M[K] extends { readonly kind: infer Kd } ? (string extends Kd ? 1 : never) : 1 }[keyof M],\n] extends [never]\n ? []\n : [problem: NeedsLiteralKind];\n\ntype Remaining<E, H> = Exclude<E, { readonly kind: keyof H & string }>;\ntype Decided<R, H> = [Remaining<ErrorOf<R>, H>] extends [never]\n ? Ok<OkOf<R> | H[keyof H]>\n : Ok<OkOf<R> | H[keyof H]> | Err<Remaining<ErrorOf<R>, H>>;\ntype Translated<R, M> = Ok<OkOf<R>> | Err<M[keyof M] | Remaining<ErrorOf<R>, M>>;\n\nfunction pick(table: object, kind: unknown): ((failure: unknown) => unknown) | undefined {\n if (typeof kind !== 'string' || !Object.prototype.hasOwnProperty.call(table, kind)) return undefined;\n return (table as Record<string, (failure: unknown) => unknown>)[kind];\n}\n\n/**\n * The only place a failure may stop: a failure whose kind has a handler becomes\n * `ok(handler(failure))`; anything else is returned untouched. Handlers are synchronous\n * and must return a value (never `undefined`/`void`).\n */\nexport function decide<R extends Result<unknown, unknown>, H extends HandlerBase<ErrorOf<R>, H>>(\n result: R & FailureGuard<R>,\n handlers: HandlerFns<ErrorOf<R>, H>,\n): Decided<R, H>;\nexport function decide(result: Result<unknown, unknown>, handlers: object): unknown {\n if (result.ok) return result;\n const handler = pick(handlers, (result.error as { kind?: unknown } | null)?.kind);\n return handler === undefined ? result : ok(handler(result.error));\n}\n\n/** Turns failures into different failures; unmapped failures and successes pass through untouched. */\nexport function translate<R extends Result<unknown, unknown>, M extends MapperBase<ErrorOf<R>, M>>(\n result: R & FailureGuard<R>,\n mappers: MapperFns<ErrorOf<R>, M>,\n ...check: KindCheck<M>\n): Translated<R, M>;\nexport function translate(result: Result<unknown, unknown>, mappers: object): unknown {\n if (result.ok) return result;\n const mapper = pick(mappers, (result.error as { kind?: unknown } | null)?.kind);\n return mapper === undefined ? result : err(mapper(result.error));\n}\n\n/** Make a result: `Result.ok(value)`, `Result.err({ kind: 'x', ... })`. */\nexport const Result: {\n readonly ok: typeof ok;\n readonly err: typeof err;\n} = { ok, err };\n\n/**\n * Apply the discipline:\n * `Trust.try` / `Trust.tryAsync` are the only boundary that may catch a throw;\n * `Trust.decide` is the only place a failure may stop; `Trust.translate` the only place it may change kind.\n */\nexport const Trust: {\n readonly try: typeof tryResult;\n readonly tryAsync: typeof tryResultAsync;\n readonly decide: typeof decide;\n readonly translate: typeof translate;\n} = { try: tryResult, tryAsync: tryResultAsync, decide, translate };\n"],"mappings":";AAwBO,SAAS,GAAM,OAAiB;AACrC,SAAO,EAAE,IAAI,MAAM,MAAM;AAC3B;AAaO,SAAS,IAAO,OAAkB;AACvC,SAAO,EAAE,IAAI,OAAO,MAAM;AAC5B;AAWO,SAAS,UAAgB,IAAa,SAA8C;AACzF,MAAI;AACF,WAAO,GAAG,GAAG,CAAC;AAAA,EAChB,SAAS,OAAO;AACd,WAAO,IAAI,QAAQ,KAAK,CAAC;AAAA,EAC3B;AACF;AAcA,eAAsB,eACpB,IACA,SACuB;AACvB,MAAI;AACF,WAAO,GAAG,MAAM,GAAG,CAAC;AAAA,EACtB,SAAS,OAAO;AACd,WAAO,IAAI,QAAQ,KAAK,CAAC;AAAA,EAC3B;AACF;AAoDA,SAAS,KAAK,OAAe,MAA4D;AACvF,MAAI,OAAO,SAAS,YAAY,CAAC,OAAO,UAAU,eAAe,KAAK,OAAO,IAAI,EAAG,QAAO;AAC3F,SAAQ,MAAwD,IAAI;AACtE;AAWO,SAAS,OAAO,QAAkC,UAA2B;AAClF,MAAI,OAAO,GAAI,QAAO;AACtB,QAAM,UAAU,KAAK,UAAW,OAAO,OAAqC,IAAI;AAChF,SAAO,YAAY,SAAY,SAAS,GAAG,QAAQ,OAAO,KAAK,CAAC;AAClE;AAQO,SAAS,UAAU,QAAkC,SAA0B;AACpF,MAAI,OAAO,GAAI,QAAO;AACtB,QAAM,SAAS,KAAK,SAAU,OAAO,OAAqC,IAAI;AAC9E,SAAO,WAAW,SAAY,SAAS,IAAI,OAAO,OAAO,KAAK,CAAC;AACjE;AAGO,IAAM,SAGT,EAAE,IAAI,IAAI;AAOP,IAAM,QAKT,EAAE,KAAK,WAAW,UAAU,gBAAgB,QAAQ,UAAU;","names":[]}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@noego/trust",
3
- "version": "0.3.0",
3
+ "version": "0.5.0-dev.0",
4
4
  "description": "Result type plus type-aware ESLint rules that make failure handling explicit: untrusted calls and throws must be caught locally and returned as Result.err.",
5
5
  "type": "module",
6
6
  "main": "dist/index.cjs",
@@ -28,6 +28,11 @@
28
28
  "import": "./dist/eslint/index.js",
29
29
  "default": "./dist/eslint/index.js"
30
30
  },
31
+ "./core": {
32
+ "types": "./dist/core/index.d.ts",
33
+ "import": "./dist/core/index.js",
34
+ "default": "./dist/core/index.js"
35
+ },
31
36
  "./package.json": "./package.json"
32
37
  },
33
38
  "files": [
@@ -41,9 +46,6 @@
41
46
  "engines": {
42
47
  "node": ">=20"
43
48
  },
44
- "dependencies": {
45
- "minimatch": "^10.0.3"
46
- },
47
49
  "peerDependencies": {
48
50
  "eslint": ">=9",
49
51
  "typescript": ">=5",
@@ -63,6 +65,7 @@
63
65
  "devDependencies": {
64
66
  "@types/node": "^22.10.0",
65
67
  "eslint": "^10.1.0",
68
+ "minimatch": "^10.0.3",
66
69
  "tsup": "^8.5.0",
67
70
  "typescript": "~5.9.3",
68
71
  "typescript-eslint": "^8.57.1",