@noego/trust 0.5.1-dev.1 → 0.5.1-dev.3

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
@@ -22,6 +22,24 @@ type Err<E> = {
22
22
  readonly ok: false;
23
23
  readonly error: E;
24
24
  };
25
+ type StatedOk<T, S extends string> = {
26
+ [K in S]: {
27
+ readonly ok: true;
28
+ readonly state: K;
29
+ readonly value: T;
30
+ };
31
+ }[S];
32
+ type StatedResult<T, E, S extends string> = StatedOk<T, S> | Err<E>;
33
+ type LiteralState<S extends string> = string extends S ? never : S;
34
+ type Stateless<R> = Extract<R, {
35
+ readonly state: unknown;
36
+ }> extends never ? R : never;
37
+ type NotResult<T> = unknown extends T ? never : Extract<T, Ok<unknown> | Err<unknown>> extends never ? T : never;
38
+ declare function state<const S extends string>(state: LiteralState<S>): StatedOk<void, S>;
39
+ declare function state<const S extends string, R extends Result<unknown, unknown>>(state: LiteralState<S>, result: R & Stateless<R> & (0 extends (1 & R) ? never : unknown)): StatedOk<OkOf<R>, S> | Extract<R, {
40
+ readonly ok: false;
41
+ }>;
42
+ declare function state<const S extends string, T>(state: LiteralState<S>, value: T, ...check: [T] extends [NotResult<T>] ? unknown extends T ? [problem: never] : [] : [problem: never]): StatedOk<T, S>;
25
43
  /** A failure is an object with a literal `kind` plus any fields. */
26
44
  type Failure<K extends string = string, Fields extends object = {}> = {
27
45
  readonly kind: K;
@@ -116,21 +134,63 @@ type KindCheck<M> = [
116
134
  type Remaining<E, H> = Exclude<E, {
117
135
  readonly kind: keyof H & string;
118
136
  }>;
119
- type Decided<R, H> = [Remaining<ErrorOf<R>, H>] extends [never] ? Ok<OkOf<R> | H[keyof H]> : Ok<OkOf<R> | H[keyof H]> | Err<Remaining<ErrorOf<R>, H>>;
120
- type Translated<R, M> = Ok<OkOf<R>> | Err<M[keyof M] | Remaining<ErrorOf<R>, M>>;
137
+ type StatedMembersOf<R> = Extract<R, {
138
+ readonly ok: true;
139
+ readonly state: string;
140
+ }>;
141
+ type HasStates<R> = [StatedMembersOf<R>] extends [never] ? false : true;
142
+ type StateGuard<R> = HasStates<R> extends true ? Exclude<Extract<R, Ok<unknown>>, StatedMembersOf<R>> extends never ? unknown : {
143
+ readonly __trust: 'mixed stated and stateless successes are not supported';
144
+ } : unknown;
145
+ type SuccessOf<R, H> = HasStates<R> extends true ? StatedMembersOf<R> | H[keyof H] : Ok<OkOf<R> | H[keyof H]>;
146
+ type RecoveryCheck<R, H> = {
147
+ [K in keyof H]: HasStates<R> extends true ? H[K] extends StatedOk<unknown, infer S extends string> ? string extends S ? 1 : never : 1 : Extract<H[K], {
148
+ readonly state: unknown;
149
+ }> extends never ? never : 1;
150
+ }[keyof H] extends never ? [] : [problem: {
151
+ readonly __trust: 'recovery must preserve the success state discipline';
152
+ }];
153
+ type Decided<R, H> = [Remaining<ErrorOf<R>, H>] extends [never] ? SuccessOf<R, H> : SuccessOf<R, H> | Err<Remaining<ErrorOf<R>, H>>;
154
+ type Translated<R, M> = (HasStates<R> extends true ? StatedMembersOf<R> : Ok<OkOf<R>>) | Err<M[keyof M] | Remaining<ErrorOf<R>, M>>;
121
155
  /**
122
156
  * The only place a failure may stop: a failure whose kind has a handler becomes
123
157
  * `ok(handler(failure))`; anything else is returned untouched. Handlers are synchronous
124
158
  * and must return a value (never `undefined`/`void`).
125
159
  */
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>;
160
+ declare function decide<R extends Result<unknown, unknown>, H extends HandlerBase<ErrorOf<R>, H>>(result: R & FailureGuard<R> & StateGuard<R>, handlers: HandlerFns<ErrorOf<R>, H>, ...check: RecoveryCheck<R, H>): Decided<R, H>;
127
161
  /** Turns failures into different failures; unmapped failures and successes pass through untouched. */
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>;
162
+ declare function translate<R extends Result<unknown, unknown>, M extends MapperBase<ErrorOf<R>, M>>(result: R & FailureGuard<R> & StateGuard<R>, mappers: MapperFns<ErrorOf<R>, M>, ...check: KindCheck<M>): Translated<R, M>;
163
+ type MatchGuard<R> = [RawErrorOf<R>] extends [never] ? HasStates<R> extends true ? StateGuard<R> : {
164
+ readonly __trust: 'match needs stated successes';
165
+ } : {
166
+ readonly __trust: 'match requires all failures to be handled first';
167
+ };
168
+ type StatesOf<R> = StatedMembersOf<R>['state'];
169
+ type MatchFns<R, H> = {
170
+ [K in keyof H]-?: (value: OkOf<Extract<R, {
171
+ readonly state: K;
172
+ }>>) => H[K];
173
+ };
174
+ type MatchBase<R, H> = {
175
+ [K in StatesOf<R>]: {} | null;
176
+ } & {
177
+ [K in keyof H]: K extends StatesOf<R> ? {} | null : never;
178
+ };
179
+ type Matched<H> = [H[keyof H]] extends [StatedOk<unknown, string>] ? H[keyof H] : Ok<H[keyof H]>;
180
+ type MatchCheck<H> = [Extract<H[keyof H], {
181
+ readonly state: unknown;
182
+ }>] extends [never] ? [] : [H[keyof H]] extends [StatedOk<unknown, infer S extends string>] ? string extends S ? [problem: {
183
+ readonly __trust: 'match needs literal output states';
184
+ }] : [] : [problem: {
185
+ readonly __trust: 'match cannot mix stated and bare returns';
186
+ }];
187
+ declare function match<R extends Result<unknown, unknown>, H extends MatchBase<R, H>>(result: R & MatchGuard<R>, handlers: MatchFns<R, H>, ...check: MatchCheck<H>): Matched<H>;
129
188
  type Result<T, E> = Ok<T> | Err<E>;
130
189
  /** Make a result: `Result.ok(value)`, `Result.err({ kind: 'x', ... })`. */
131
190
  declare const Result: {
132
191
  readonly ok: typeof ok;
133
192
  readonly err: typeof err;
193
+ readonly state: typeof state;
134
194
  };
135
195
  /**
136
196
  * Apply the discipline:
@@ -142,6 +202,7 @@ declare const Trust: {
142
202
  readonly tryAsync: typeof tryResultAsync;
143
203
  readonly decide: typeof decide;
144
204
  readonly translate: typeof translate;
205
+ readonly match: typeof match;
145
206
  };
146
207
 
147
- export { type Err, type Failure, type Ok, Result, Trust, decide, err, ok, translate, tryResult, tryResultAsync };
208
+ export { type Err, type Failure, type Ok, Result, type StatedOk, type StatedResult, Trust, decide, err, match, ok, state, translate, tryResult, tryResultAsync };
package/dist/index.d.ts CHANGED
@@ -22,6 +22,24 @@ type Err<E> = {
22
22
  readonly ok: false;
23
23
  readonly error: E;
24
24
  };
25
+ type StatedOk<T, S extends string> = {
26
+ [K in S]: {
27
+ readonly ok: true;
28
+ readonly state: K;
29
+ readonly value: T;
30
+ };
31
+ }[S];
32
+ type StatedResult<T, E, S extends string> = StatedOk<T, S> | Err<E>;
33
+ type LiteralState<S extends string> = string extends S ? never : S;
34
+ type Stateless<R> = Extract<R, {
35
+ readonly state: unknown;
36
+ }> extends never ? R : never;
37
+ type NotResult<T> = unknown extends T ? never : Extract<T, Ok<unknown> | Err<unknown>> extends never ? T : never;
38
+ declare function state<const S extends string>(state: LiteralState<S>): StatedOk<void, S>;
39
+ declare function state<const S extends string, R extends Result<unknown, unknown>>(state: LiteralState<S>, result: R & Stateless<R> & (0 extends (1 & R) ? never : unknown)): StatedOk<OkOf<R>, S> | Extract<R, {
40
+ readonly ok: false;
41
+ }>;
42
+ declare function state<const S extends string, T>(state: LiteralState<S>, value: T, ...check: [T] extends [NotResult<T>] ? unknown extends T ? [problem: never] : [] : [problem: never]): StatedOk<T, S>;
25
43
  /** A failure is an object with a literal `kind` plus any fields. */
26
44
  type Failure<K extends string = string, Fields extends object = {}> = {
27
45
  readonly kind: K;
@@ -116,21 +134,63 @@ type KindCheck<M> = [
116
134
  type Remaining<E, H> = Exclude<E, {
117
135
  readonly kind: keyof H & string;
118
136
  }>;
119
- type Decided<R, H> = [Remaining<ErrorOf<R>, H>] extends [never] ? Ok<OkOf<R> | H[keyof H]> : Ok<OkOf<R> | H[keyof H]> | Err<Remaining<ErrorOf<R>, H>>;
120
- type Translated<R, M> = Ok<OkOf<R>> | Err<M[keyof M] | Remaining<ErrorOf<R>, M>>;
137
+ type StatedMembersOf<R> = Extract<R, {
138
+ readonly ok: true;
139
+ readonly state: string;
140
+ }>;
141
+ type HasStates<R> = [StatedMembersOf<R>] extends [never] ? false : true;
142
+ type StateGuard<R> = HasStates<R> extends true ? Exclude<Extract<R, Ok<unknown>>, StatedMembersOf<R>> extends never ? unknown : {
143
+ readonly __trust: 'mixed stated and stateless successes are not supported';
144
+ } : unknown;
145
+ type SuccessOf<R, H> = HasStates<R> extends true ? StatedMembersOf<R> | H[keyof H] : Ok<OkOf<R> | H[keyof H]>;
146
+ type RecoveryCheck<R, H> = {
147
+ [K in keyof H]: HasStates<R> extends true ? H[K] extends StatedOk<unknown, infer S extends string> ? string extends S ? 1 : never : 1 : Extract<H[K], {
148
+ readonly state: unknown;
149
+ }> extends never ? never : 1;
150
+ }[keyof H] extends never ? [] : [problem: {
151
+ readonly __trust: 'recovery must preserve the success state discipline';
152
+ }];
153
+ type Decided<R, H> = [Remaining<ErrorOf<R>, H>] extends [never] ? SuccessOf<R, H> : SuccessOf<R, H> | Err<Remaining<ErrorOf<R>, H>>;
154
+ type Translated<R, M> = (HasStates<R> extends true ? StatedMembersOf<R> : Ok<OkOf<R>>) | Err<M[keyof M] | Remaining<ErrorOf<R>, M>>;
121
155
  /**
122
156
  * The only place a failure may stop: a failure whose kind has a handler becomes
123
157
  * `ok(handler(failure))`; anything else is returned untouched. Handlers are synchronous
124
158
  * and must return a value (never `undefined`/`void`).
125
159
  */
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>;
160
+ declare function decide<R extends Result<unknown, unknown>, H extends HandlerBase<ErrorOf<R>, H>>(result: R & FailureGuard<R> & StateGuard<R>, handlers: HandlerFns<ErrorOf<R>, H>, ...check: RecoveryCheck<R, H>): Decided<R, H>;
127
161
  /** Turns failures into different failures; unmapped failures and successes pass through untouched. */
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>;
162
+ declare function translate<R extends Result<unknown, unknown>, M extends MapperBase<ErrorOf<R>, M>>(result: R & FailureGuard<R> & StateGuard<R>, mappers: MapperFns<ErrorOf<R>, M>, ...check: KindCheck<M>): Translated<R, M>;
163
+ type MatchGuard<R> = [RawErrorOf<R>] extends [never] ? HasStates<R> extends true ? StateGuard<R> : {
164
+ readonly __trust: 'match needs stated successes';
165
+ } : {
166
+ readonly __trust: 'match requires all failures to be handled first';
167
+ };
168
+ type StatesOf<R> = StatedMembersOf<R>['state'];
169
+ type MatchFns<R, H> = {
170
+ [K in keyof H]-?: (value: OkOf<Extract<R, {
171
+ readonly state: K;
172
+ }>>) => H[K];
173
+ };
174
+ type MatchBase<R, H> = {
175
+ [K in StatesOf<R>]: {} | null;
176
+ } & {
177
+ [K in keyof H]: K extends StatesOf<R> ? {} | null : never;
178
+ };
179
+ type Matched<H> = [H[keyof H]] extends [StatedOk<unknown, string>] ? H[keyof H] : Ok<H[keyof H]>;
180
+ type MatchCheck<H> = [Extract<H[keyof H], {
181
+ readonly state: unknown;
182
+ }>] extends [never] ? [] : [H[keyof H]] extends [StatedOk<unknown, infer S extends string>] ? string extends S ? [problem: {
183
+ readonly __trust: 'match needs literal output states';
184
+ }] : [] : [problem: {
185
+ readonly __trust: 'match cannot mix stated and bare returns';
186
+ }];
187
+ declare function match<R extends Result<unknown, unknown>, H extends MatchBase<R, H>>(result: R & MatchGuard<R>, handlers: MatchFns<R, H>, ...check: MatchCheck<H>): Matched<H>;
129
188
  type Result<T, E> = Ok<T> | Err<E>;
130
189
  /** Make a result: `Result.ok(value)`, `Result.err({ kind: 'x', ... })`. */
131
190
  declare const Result: {
132
191
  readonly ok: typeof ok;
133
192
  readonly err: typeof err;
193
+ readonly state: typeof state;
134
194
  };
135
195
  /**
136
196
  * Apply the discipline:
@@ -142,6 +202,7 @@ declare const Trust: {
142
202
  readonly tryAsync: typeof tryResultAsync;
143
203
  readonly decide: typeof decide;
144
204
  readonly translate: typeof translate;
205
+ readonly match: typeof match;
145
206
  };
146
207
 
147
- export { type Err, type Failure, type Ok, Result, Trust, decide, err, ok, translate, tryResult, tryResultAsync };
208
+ export { type Err, type Failure, type Ok, Result, type StatedOk, type StatedResult, Trust, decide, err, match, ok, state, translate, tryResult, tryResultAsync };
package/dist/index.js CHANGED
@@ -1,9 +1,24 @@
1
1
  // src/index.ts
2
+ var resultBrand = /* @__PURE__ */ Symbol.for("@noego/trust/result");
3
+ function brand(value) {
4
+ return Object.defineProperty(value, resultBrand, { value: true });
5
+ }
6
+ function isResult(value) {
7
+ return (typeof value === "object" && value !== null || typeof value === "function") && resultBrand in value;
8
+ }
9
+ function state(state2, value) {
10
+ if (arguments.length === 1) return brand({ ok: true, state: state2, value: void 0 });
11
+ if (isResult(value)) {
12
+ if (value.ok === false) return value;
13
+ return brand({ ok: true, state: state2, value: value.value });
14
+ }
15
+ return brand({ ok: true, state: state2, value });
16
+ }
2
17
  function ok(value) {
3
- return { ok: true, value };
18
+ return brand({ ok: true, value });
4
19
  }
5
20
  function err(error) {
6
- return { ok: false, error };
21
+ return brand({ ok: false, error });
7
22
  }
8
23
  function tryResult(fn, onError) {
9
24
  try {
@@ -26,21 +41,32 @@ function pick(table, kind) {
26
41
  function decide(result, handlers) {
27
42
  if (result.ok) return result;
28
43
  const handler = pick(handlers, result.error?.kind);
29
- return handler === void 0 ? result : ok(handler(result.error));
44
+ if (handler === void 0) return result;
45
+ const value = handler(result.error);
46
+ return isResult(value) ? value : ok(value);
30
47
  }
31
48
  function translate(result, mappers) {
32
49
  if (result.ok) return result;
33
50
  const mapper = pick(mappers, result.error?.kind);
34
51
  return mapper === void 0 ? result : err(mapper(result.error));
35
52
  }
36
- var Result = { ok, err };
37
- var Trust = { try: tryResult, tryAsync: tryResultAsync, decide, translate };
53
+ function match(result, handlers) {
54
+ if (!result.ok) return result;
55
+ const handler = pick(handlers, result.state);
56
+ if (handler === void 0) return result;
57
+ const value = handler(result.value);
58
+ return isResult(value) ? value : ok(value);
59
+ }
60
+ var Result = { ok, err, state };
61
+ var Trust = { try: tryResult, tryAsync: tryResultAsync, decide, translate, match };
38
62
  export {
39
63
  Result,
40
64
  Trust,
41
65
  decide,
42
66
  err,
67
+ match,
43
68
  ok,
69
+ state,
44
70
  translate,
45
71
  tryResult,
46
72
  tryResultAsync
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 * 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":[]}
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\nexport type StatedOk<T, S extends string> = { [K in S]: { readonly ok: true; readonly state: K; readonly value: T } }[S];\nexport type StatedResult<T, E, S extends string> = StatedOk<T, S> | Err<E>;\n\ntype LiteralState<S extends string> = string extends S ? never : S;\ntype Stateless<R> = Extract<R, { readonly state: unknown }> extends never ? R : never;\ntype NotResult<T> = unknown extends T ? never : Extract<T, Ok<unknown> | Err<unknown>> extends never ? T : never;\n\nconst resultBrand = Symbol.for('@noego/trust/result');\nfunction brand<T extends object>(value: T): T {\n return Object.defineProperty(value, resultBrand, { value: true });\n}\nfunction isResult(value: unknown): value is Result<unknown, unknown> {\n return ((typeof value === 'object' && value !== null) || typeof value === 'function')\n && resultBrand in value;\n}\n\nexport function state<const S extends string>(state: LiteralState<S>): StatedOk<void, S>;\nexport function state<const S extends string, R extends Result<unknown, unknown>>(\n state: LiteralState<S>, result: R & Stateless<R> & (0 extends (1 & R) ? never : unknown),\n): StatedOk<OkOf<R>, S> | Extract<R, { readonly ok: false }>;\nexport function state<const S extends string, T>(\n state: LiteralState<S>, value: T,\n ...check: [T] extends [NotResult<T>] ? unknown extends T ? [problem: never] : [] : [problem: never]\n): StatedOk<T, S>;\nexport function state(state: string, value?: unknown): Result<unknown, unknown> {\n if (arguments.length === 1) return brand({ ok: true, state, value: undefined });\n if (isResult(value)) {\n if (value.ok === false) return value;\n return brand({ ok: true, state, value: value.value });\n }\n return brand({ ok: true, state, value });\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\n/** Wraps a success value. */\nexport function ok<T>(value: T): Ok<T> {\n return brand({ 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 brand({ 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 StatedMembersOf<R> = Extract<R, { readonly ok: true; readonly state: string }>;\ntype HasStates<R> = [StatedMembersOf<R>] extends [never] ? false : true;\ntype StateGuard<R> = HasStates<R> extends true\n ? Exclude<Extract<R, Ok<unknown>>, StatedMembersOf<R>> extends never ? unknown\n : { readonly __trust: 'mixed stated and stateless successes are not supported' }\n : unknown;\ntype SuccessOf<R, H> = HasStates<R> extends true ? StatedMembersOf<R> | H[keyof H] : Ok<OkOf<R> | H[keyof H]>;\ntype RecoveryCheck<R, H> = {\n [K in keyof H]: HasStates<R> extends true\n ? H[K] extends StatedOk<unknown, infer S extends string> ? string extends S ? 1 : never : 1\n : Extract<H[K], { readonly state: unknown }> extends never ? never : 1\n}[keyof H] extends never ? [] : [problem: { readonly __trust: 'recovery must preserve the success state discipline' }];\ntype Decided<R, H> = [Remaining<ErrorOf<R>, H>] extends [never]\n ? SuccessOf<R, H>\n : SuccessOf<R, H> | Err<Remaining<ErrorOf<R>, H>>;\ntype Translated<R, M> = (HasStates<R> extends true ? StatedMembersOf<R> : 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> & StateGuard<R>,\n handlers: HandlerFns<ErrorOf<R>, H>,\n ...check: RecoveryCheck<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 if (handler === undefined) return result;\n const value = handler(result.error);\n return isResult(value) ? value : ok(value);\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> & StateGuard<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\ntype MatchGuard<R> = [RawErrorOf<R>] extends [never]\n ? HasStates<R> extends true ? StateGuard<R> : { readonly __trust: 'match needs stated successes' }\n : { readonly __trust: 'match requires all failures to be handled first' };\ntype StatesOf<R> = StatedMembersOf<R>['state'];\ntype MatchFns<R, H> = {\n [K in keyof H]-?: (value: OkOf<Extract<R, { readonly state: K }>>) => H[K];\n};\ntype MatchBase<R, H> = { [K in StatesOf<R>]: {} | null } & {\n [K in keyof H]: K extends StatesOf<R> ? {} | null : never;\n};\ntype Matched<H> = [H[keyof H]] extends [StatedOk<unknown, string>] ? H[keyof H] : Ok<H[keyof H]>;\ntype MatchCheck<H> = [Extract<H[keyof H], { readonly state: unknown }>] extends [never]\n ? [] : [H[keyof H]] extends [StatedOk<unknown, infer S extends string>]\n ? string extends S ? [problem: { readonly __trust: 'match needs literal output states' }] : []\n : [problem: { readonly __trust: 'match cannot mix stated and bare returns' }];\n\nexport function match<R extends Result<unknown, unknown>, H extends MatchBase<R, H>>(\n result: R & MatchGuard<R>, handlers: MatchFns<R, H>, ...check: MatchCheck<H>\n): Matched<H>;\nexport function match(result: Result<unknown, unknown>, handlers: object): unknown {\n if (!result.ok) return result;\n const handler = pick(handlers, (result as { state?: unknown }).state);\n if (handler === undefined) return result;\n const value = handler(result.value);\n return isResult(value) ? value : ok(value);\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 readonly state: typeof state;\n} = { ok, err, state };\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 readonly match: typeof match;\n} = { try: tryResult, tryAsync: tryResultAsync, decide, translate, match };\n"],"mappings":";AA2BA,IAAM,cAAc,uBAAO,IAAI,qBAAqB;AACpD,SAAS,MAAwB,OAAa;AAC5C,SAAO,OAAO,eAAe,OAAO,aAAa,EAAE,OAAO,KAAK,CAAC;AAClE;AACA,SAAS,SAAS,OAAmD;AACnE,UAAS,OAAO,UAAU,YAAY,UAAU,QAAS,OAAO,UAAU,eACrE,eAAe;AACtB;AAUO,SAAS,MAAMA,QAAe,OAA2C;AAC9E,MAAI,UAAU,WAAW,EAAG,QAAO,MAAM,EAAE,IAAI,MAAM,OAAAA,QAAO,OAAO,OAAU,CAAC;AAC9E,MAAI,SAAS,KAAK,GAAG;AACnB,QAAI,MAAM,OAAO,MAAO,QAAO;AAC/B,WAAO,MAAM,EAAE,IAAI,MAAM,OAAAA,QAAO,OAAO,MAAM,MAAM,CAAC;AAAA,EACtD;AACA,SAAO,MAAM,EAAE,IAAI,MAAM,OAAAA,QAAO,MAAM,CAAC;AACzC;AAMO,SAAS,GAAM,OAAiB;AACrC,SAAO,MAAM,EAAE,IAAI,MAAM,MAAM,CAAC;AAClC;AAaO,SAAS,IAAO,OAAkB;AACvC,SAAO,MAAM,EAAE,IAAI,OAAO,MAAM,CAAC;AACnC;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;AAgEA,SAAS,KAAK,OAAe,MAA4D;AACvF,MAAI,OAAO,SAAS,YAAY,CAAC,OAAO,UAAU,eAAe,KAAK,OAAO,IAAI,EAAG,QAAO;AAC3F,SAAQ,MAAwD,IAAI;AACtE;AAYO,SAAS,OAAO,QAAkC,UAA2B;AAClF,MAAI,OAAO,GAAI,QAAO;AACtB,QAAM,UAAU,KAAK,UAAW,OAAO,OAAqC,IAAI;AAChF,MAAI,YAAY,OAAW,QAAO;AAClC,QAAM,QAAQ,QAAQ,OAAO,KAAK;AAClC,SAAO,SAAS,KAAK,IAAI,QAAQ,GAAG,KAAK;AAC3C;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;AAqBO,SAAS,MAAM,QAAkC,UAA2B;AACjF,MAAI,CAAC,OAAO,GAAI,QAAO;AACvB,QAAM,UAAU,KAAK,UAAW,OAA+B,KAAK;AACpE,MAAI,YAAY,OAAW,QAAO;AAClC,QAAM,QAAQ,QAAQ,OAAO,KAAK;AAClC,SAAO,SAAS,KAAK,IAAI,QAAQ,GAAG,KAAK;AAC3C;AAGO,IAAM,SAIT,EAAE,IAAI,KAAK,MAAM;AAOd,IAAM,QAMT,EAAE,KAAK,WAAW,UAAU,gBAAgB,QAAQ,WAAW,MAAM;","names":["state"]}
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@noego/trust",
3
- "version": "0.5.1-dev.1",
3
+ "version": "0.5.1-dev.3",
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",
@@ -73,9 +73,9 @@
73
73
  }
74
74
  },
75
75
  "optionalDependencies": {
76
- "@noego/trust-darwin-arm64": "0.5.1",
77
- "@noego/trust-linux-x64-gnu": "0.5.1",
78
- "@noego/trust-win32-x64-msvc": "0.5.1"
76
+ "@noego/trust-darwin-arm64": "0.5.1-dev.0",
77
+ "@noego/trust-linux-x64-gnu": "0.5.1-dev.0",
78
+ "@noego/trust-win32-x64-msvc": "0.5.1-dev.0"
79
79
  },
80
80
  "devDependencies": {
81
81
  "@jridgewell/trace-mapping": "^0.3.31",