@noego/trust 0.1.0 → 0.3.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/README.md CHANGED
@@ -24,6 +24,41 @@ const loaded = Result.try(() => JSON.parse(text), () => ({ kind: 'bad_json' }) a
24
24
  const fetched = await Result.tryAsync(() => client.get(url), (cause) => toHttpError(cause));
25
25
  ```
26
26
 
27
+ ## Handling a failure: return it or decide it
28
+
29
+ Rules:
30
+
31
+ 1. A failure is an object with a literal `kind`: `{ kind: 'NotFound', id }`.
32
+ 2. On failure either `return r` (pass it up) or `decide` it. Nothing else may stop a failure.
33
+ 3. A `decide` handler returns a value (never `undefined`/`void`); that value says what replaced the failure.
34
+ 4. Leave fallible functions' return types inferred so the failure kinds flow to the caller.
35
+ 5. A thrown error from outside code becomes a named failure in `Result.try` / `Result.tryAsync`.
36
+
37
+ ```ts
38
+ import { Result } from '@noego/trust';
39
+
40
+ async function lookup(id: number) {
41
+ const found = await Result.tryAsync(
42
+ () => db.find(id),
43
+ (cause) => ({ kind: 'ConnectionFailed', cause }),
44
+ );
45
+ if (!found.ok) return found;
46
+ return found.value ? Result.ok(found.value) : Result.err({ kind: 'NotFound', id });
47
+ }
48
+
49
+ const r = await lookup(7);
50
+ // NotFound becomes a guest value; ConnectionFailed stays a failure in the type.
51
+ const user = Result.decide(r, { NotFound: () => GUEST });
52
+ if (!user.ok) return user; // Err<{ kind: 'ConnectionFailed'; ... }>
53
+ ```
54
+
55
+ `Result.translate(r, { NotFound: (f) => ({ kind: 'Missing', id: f.id }) })` turns one failure into another.
56
+ Handlers and mappers are synchronous: async handlers are not supported.
57
+
58
+ ### Breaking in 0.3.0
59
+
60
+ An inline `err({ kind: ... })` now keeps its literal kind, so a callback returning several different failures no longer collapses to `{ kind: string }`. Give the receiving function a union type, or let it infer the callback's whole return type.
61
+
27
62
  ## Lint: `@noego/trust/eslint`
28
63
 
29
64
  Rules (typed linting required for `untrusted-call-must-return-result`):
@@ -54,7 +89,7 @@ export default [
54
89
  }
55
90
  ```
56
91
 
57
- - `extend`: a preset (`default`) or a relative path. Chains are followed.
92
+ - `extend`: a preset (`js`, `node`, `web`, `default`) or a relative path. Chains are followed.
58
93
  - `trust` / `distrust`: origins. An entry covers the origin itself, its subpaths (`node:fs` covers
59
94
  `node:fs/promises`), and its members (`js:JSON` covers `js:JSON.parse`). Lookup walks from this file toward the
60
95
  root preset; the first level whose `distrust` matches makes it untrusted, so `distrust` removes inherited trust.
@@ -68,6 +103,37 @@ A call is also trusted when its declared return type is `Result` / `Promise<Resu
68
103
  unless its origin is explicitly distrusted. `Result.err`, `Result.try` and `Result.tryAsync` are recognised
69
104
  by declaration, not by name.
70
105
 
106
+ ### Presets
107
+
108
+ | Preset | Extends | Trusts |
109
+ |---|---|---|
110
+ | `js` | | Pure JavaScript built-ins that cannot fail on typed input (`js:Array`, `js:Map`, `js:Math`, …), the same in every runtime. |
111
+ | `node` | `js` | Node built-in APIs, audited member by member against the Node v24 source (v26 recorded). |
112
+ | `web` | `js` | Nothing beyond `js` yet: browser globals have not been audited. |
113
+ | `default` | `node` | Alias of `node`. |
114
+
115
+ The `node` list trusts a call only if arguments that satisfy its TypeScript types cannot make it throw or fail
116
+ asynchronously (rejected promise, error-first callback, an `'error'` event caused by the call). Doing I/O or
117
+ calling native code is fine on its own; a reachable failure path is not. An exception from a callback or
118
+ listener you pass counts as a failure. Proxy traps, getters, implicit coercion and TypeScript-unsound inputs do
119
+ not, and neither do engine resource limits. Whole-module or whole-class entries appear only where every member
120
+ was trusted, with explicit `distrust` entries for any member that can fail under a trusted class. The evidence
121
+ for every entry is in `research/node-api/`.
122
+
123
+ A project with several runtimes gives each area its own trust config:
124
+
125
+ ```js
126
+ // eslint.config.js
127
+ export default [
128
+ ...typedConfig({ files: ['server/**/*.ts'], configFile: 'trust.server.json' }), // { "extend": "node" }
129
+ ...typedConfig({ files: ['web/**/*.ts'], configFile: 'trust.web.json' }), // { "extend": "web" }
130
+ ...typedConfig({ files: ['shared/**/*.ts'], configFile: 'trust.shared.json' }), // { "extend": "js" }
131
+ ];
132
+ ```
133
+
134
+ Origins depend on the project's TypeScript libs: with the DOM lib loaded (the default when `lib` is not set),
135
+ web globals such as `URL`, `TextEncoder` and `URLSearchParams` resolve to `js:` origins, not `node:`.
136
+
71
137
  ### Origins
72
138
 
73
139
  | Kind | Origin | Example |