@effected/engine 0.9.0 → 0.11.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/ErrorText.js +98 -0
- package/README.md +2 -2
- package/index.d.ts +75 -0
- package/index.js +2 -1
- package/internal/causeMessage.js +57 -0
- package/package.json +2 -2
- package/tsdoc-metadata.json +1 -1
package/ErrorText.js
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
import { causeMessage } from "./internal/causeMessage.js";
|
|
2
|
+
import { Predicate } from "effect";
|
|
3
|
+
|
|
4
|
+
// src/ErrorText.ts
|
|
5
|
+
const describe = (value) => {
|
|
6
|
+
if (Predicate.isString(value)) return value;
|
|
7
|
+
if (value === void 0 || value === null) return String(value);
|
|
8
|
+
if (typeof value !== "object" && typeof value !== "function") return String(value);
|
|
9
|
+
try {
|
|
10
|
+
if (Predicate.hasProperty(value, "message") && Predicate.isString(value.message)) return value.message;
|
|
11
|
+
} catch {}
|
|
12
|
+
try {
|
|
13
|
+
const json = JSON.stringify(value);
|
|
14
|
+
if (json !== void 0) return json;
|
|
15
|
+
} catch {}
|
|
16
|
+
try {
|
|
17
|
+
return String(value);
|
|
18
|
+
} catch {
|
|
19
|
+
return "[unprintable value]";
|
|
20
|
+
}
|
|
21
|
+
};
|
|
22
|
+
/**
|
|
23
|
+
* Any value as error text, without ever throwing: the one implementation every front end of a tool uses, so a CLI and
|
|
24
|
+
* an MCP server describe the same failure with the same words.
|
|
25
|
+
*
|
|
26
|
+
* @remarks
|
|
27
|
+
* Every member is pure and total. None sanitises its result: text read from a value you do not control may carry
|
|
28
|
+
* escape sequences, so sanitise it before printing it to a terminal. `@effected/cli` publishes the same functions as
|
|
29
|
+
* `Fmt.describe`, `Fmt.causeMessage` and `Fmt.errorText`, which delegate here.
|
|
30
|
+
*
|
|
31
|
+
* The anti-pattern this replaces is the per-site fallback `error instanceof Error ? error.message : String(error)`:
|
|
32
|
+
* it misses an error from another realm and a plain `{ message }` object, reads nothing along the `cause` chain, and
|
|
33
|
+
* throws on a value whose `toString` throws or which has no prototype.
|
|
34
|
+
*
|
|
35
|
+
* @example
|
|
36
|
+
* ```ts
|
|
37
|
+
* import { ErrorText } from "@effected/engine"
|
|
38
|
+
*
|
|
39
|
+
* const failure = new Error("Failed to execute statement", { cause: new Error("SQLITE_BUSY: database is locked") })
|
|
40
|
+
* console.log(ErrorText.of(failure))
|
|
41
|
+
* // => "Failed to execute statement: SQLITE_BUSY: database is locked"
|
|
42
|
+
* console.log(ErrorText.of({ code: 7 }))
|
|
43
|
+
* // => "{\"code\":7}"
|
|
44
|
+
* ```
|
|
45
|
+
*
|
|
46
|
+
* @public
|
|
47
|
+
*/
|
|
48
|
+
var ErrorText = class {
|
|
49
|
+
constructor() {}
|
|
50
|
+
/**
|
|
51
|
+
* Any value as text, without ever throwing.
|
|
52
|
+
*
|
|
53
|
+
* @remarks
|
|
54
|
+
* A string is itself; a number, boolean, bigint or symbol is `String(value)`; `undefined` and `null` are
|
|
55
|
+
* `"undefined"` and `"null"`. A value with a string `message` (an `Error`, one from another realm, a plain
|
|
56
|
+
* `{ message }`) is that message, even an empty one. Anything else is its JSON, or `String(value)` when it has none
|
|
57
|
+
* (a cycle, a function), or `"[unprintable value]"` when that throws too. A getter that throws is a value with no
|
|
58
|
+
* message.
|
|
59
|
+
*
|
|
60
|
+
* For the messages along an error's `cause` chain, use {@link ErrorText.causeMessage}; for the two combined, use
|
|
61
|
+
* {@link ErrorText.of}.
|
|
62
|
+
*
|
|
63
|
+
* @param value - the value
|
|
64
|
+
*/
|
|
65
|
+
static describe = describe;
|
|
66
|
+
/**
|
|
67
|
+
* Every distinct non-empty message along a value's `cause` chain, nearest first and joined with `: `, or
|
|
68
|
+
* `undefined` when nothing along it has one.
|
|
69
|
+
*
|
|
70
|
+
* @remarks
|
|
71
|
+
* The kit's one guarded cause-message read, the one its own errors render a preserved cause with. A node's message
|
|
72
|
+
* is a thrown string or a non-empty string `message` property, read without `instanceof Error`, so an error from
|
|
73
|
+
* another realm or a plain `{ message }` object counts. A deeper message the joined text already contains is not
|
|
74
|
+
* repeated, and one that contains the joined text replaces it, so a `SqlError` wrapping SQLite's own text reads
|
|
75
|
+
* `Failed to execute statement: SQLITE_BUSY: database is locked`. It is the whole chain, not the innermost message
|
|
76
|
+
* alone. The walk stops after eight nodes, so a cyclic chain terminates.
|
|
77
|
+
*
|
|
78
|
+
* Never throws: a `message` getter that throws leaves that node without text, and a `cause` getter that throws ends
|
|
79
|
+
* the walk with the text found so far, `undefined` when there is none.
|
|
80
|
+
*
|
|
81
|
+
* @param value - the error, or whatever was thrown
|
|
82
|
+
*/
|
|
83
|
+
static causeMessage = causeMessage;
|
|
84
|
+
/**
|
|
85
|
+
* The text of an unknown failure: {@link ErrorText.causeMessage} when the chain carries a message, otherwise
|
|
86
|
+
* {@link ErrorText.describe}.
|
|
87
|
+
*
|
|
88
|
+
* @remarks
|
|
89
|
+
* Exactly `ErrorText.causeMessage(value) ?? ErrorText.describe(value)`, the fallback every I/O site would otherwise
|
|
90
|
+
* spell out by hand. An error whose message is empty and whose chain carries none is `""`, as `describe` reads it.
|
|
91
|
+
* Never throws.
|
|
92
|
+
*
|
|
93
|
+
* @param value - the error, or whatever was thrown
|
|
94
|
+
*/
|
|
95
|
+
static of = (value) => causeMessage(value) ?? describe(value);
|
|
96
|
+
};
|
|
97
|
+
|
|
98
|
+
export { ErrorText };
|
package/README.md
CHANGED
|
@@ -8,10 +8,10 @@
|
|
|
8
8
|
Platform-free primitives shared by every front end of an Effect v4 tool. A carrier-pattern tool (a CLI, an MCP server, an LSP server) ships more than one bin behind one meta-package, and every one of those front ends needs to answer the same handful of questions the same way: which carrier was I installed through, and what version line does that make me. This package holds those primitives once, so a consumer's own `engine` package can depend on them without also depending on `@effected/cli` or any other front end.
|
|
9
9
|
|
|
10
10
|
> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
|
|
11
|
-
> Effect v4 (`effect`
|
|
11
|
+
> Effect v4 (`effect` `~4.1.0`) and still in `0.x` development. Stable Effect
|
|
12
12
|
> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
|
|
13
13
|
> `@effect/*` versions on the line the kit is built and tested against, install
|
|
14
|
-
> [`@effected/pnpm-plugin-
|
|
14
|
+
> [`@effected/pnpm-plugin-effected`](https://www.npmjs.com/package/@effected/pnpm-plugin-effected).
|
|
15
15
|
>
|
|
16
16
|
> **Stability: unstable.** This package's API surface is not yet considered
|
|
17
17
|
> complete and may change across `0.x` releases. Pin an exact version — even a
|
package/index.d.ts
CHANGED
|
@@ -87,6 +87,81 @@ export declare const withDistributionVersion: (distribution: Option.Option<Distr
|
|
|
87
87
|
* @public
|
|
88
88
|
*/
|
|
89
89
|
export declare const withDistribution: (distribution: Distribution | null | undefined) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
|
|
90
|
+
/**
|
|
91
|
+
* Any value as error text, without ever throwing: the one implementation every front end of a tool uses, so a CLI and
|
|
92
|
+
* an MCP server describe the same failure with the same words.
|
|
93
|
+
*
|
|
94
|
+
* @remarks
|
|
95
|
+
* Every member is pure and total. None sanitises its result: text read from a value you do not control may carry
|
|
96
|
+
* escape sequences, so sanitise it before printing it to a terminal. `@effected/cli` publishes the same functions as
|
|
97
|
+
* `Fmt.describe`, `Fmt.causeMessage` and `Fmt.errorText`, which delegate here.
|
|
98
|
+
*
|
|
99
|
+
* The anti-pattern this replaces is the per-site fallback `error instanceof Error ? error.message : String(error)`:
|
|
100
|
+
* it misses an error from another realm and a plain `{ message }` object, reads nothing along the `cause` chain, and
|
|
101
|
+
* throws on a value whose `toString` throws or which has no prototype.
|
|
102
|
+
*
|
|
103
|
+
* @example
|
|
104
|
+
* ```ts
|
|
105
|
+
* import { ErrorText } from "@effected/engine"
|
|
106
|
+
*
|
|
107
|
+
* const failure = new Error("Failed to execute statement", { cause: new Error("SQLITE_BUSY: database is locked") })
|
|
108
|
+
* console.log(ErrorText.of(failure))
|
|
109
|
+
* // => "Failed to execute statement: SQLITE_BUSY: database is locked"
|
|
110
|
+
* console.log(ErrorText.of({ code: 7 }))
|
|
111
|
+
* // => "{\"code\":7}"
|
|
112
|
+
* ```
|
|
113
|
+
*
|
|
114
|
+
* @public
|
|
115
|
+
*/
|
|
116
|
+
export declare class ErrorText {
|
|
117
|
+
private constructor();
|
|
118
|
+
/**
|
|
119
|
+
* Any value as text, without ever throwing.
|
|
120
|
+
*
|
|
121
|
+
* @remarks
|
|
122
|
+
* A string is itself; a number, boolean, bigint or symbol is `String(value)`; `undefined` and `null` are
|
|
123
|
+
* `"undefined"` and `"null"`. A value with a string `message` (an `Error`, one from another realm, a plain
|
|
124
|
+
* `{ message }`) is that message, even an empty one. Anything else is its JSON, or `String(value)` when it has none
|
|
125
|
+
* (a cycle, a function), or `"[unprintable value]"` when that throws too. A getter that throws is a value with no
|
|
126
|
+
* message.
|
|
127
|
+
*
|
|
128
|
+
* For the messages along an error's `cause` chain, use {@link ErrorText.causeMessage}; for the two combined, use
|
|
129
|
+
* {@link ErrorText.of}.
|
|
130
|
+
*
|
|
131
|
+
* @param value - the value
|
|
132
|
+
*/
|
|
133
|
+
static readonly describe: (value: unknown) => string;
|
|
134
|
+
/**
|
|
135
|
+
* Every distinct non-empty message along a value's `cause` chain, nearest first and joined with `: `, or
|
|
136
|
+
* `undefined` when nothing along it has one.
|
|
137
|
+
*
|
|
138
|
+
* @remarks
|
|
139
|
+
* The kit's one guarded cause-message read, the one its own errors render a preserved cause with. A node's message
|
|
140
|
+
* is a thrown string or a non-empty string `message` property, read without `instanceof Error`, so an error from
|
|
141
|
+
* another realm or a plain `{ message }` object counts. A deeper message the joined text already contains is not
|
|
142
|
+
* repeated, and one that contains the joined text replaces it, so a `SqlError` wrapping SQLite's own text reads
|
|
143
|
+
* `Failed to execute statement: SQLITE_BUSY: database is locked`. It is the whole chain, not the innermost message
|
|
144
|
+
* alone. The walk stops after eight nodes, so a cyclic chain terminates.
|
|
145
|
+
*
|
|
146
|
+
* Never throws: a `message` getter that throws leaves that node without text, and a `cause` getter that throws ends
|
|
147
|
+
* the walk with the text found so far, `undefined` when there is none.
|
|
148
|
+
*
|
|
149
|
+
* @param value - the error, or whatever was thrown
|
|
150
|
+
*/
|
|
151
|
+
static readonly causeMessage: (value: unknown) => string | undefined;
|
|
152
|
+
/**
|
|
153
|
+
* The text of an unknown failure: {@link ErrorText.causeMessage} when the chain carries a message, otherwise
|
|
154
|
+
* {@link ErrorText.describe}.
|
|
155
|
+
*
|
|
156
|
+
* @remarks
|
|
157
|
+
* Exactly `ErrorText.causeMessage(value) ?? ErrorText.describe(value)`, the fallback every I/O site would otherwise
|
|
158
|
+
* spell out by hand. An error whose message is empty and whose chain carries none is `""`, as `describe` reads it.
|
|
159
|
+
* Never throws.
|
|
160
|
+
*
|
|
161
|
+
* @param value - the error, or whatever was thrown
|
|
162
|
+
*/
|
|
163
|
+
static readonly of: (value: unknown) => string;
|
|
164
|
+
}
|
|
90
165
|
/**
|
|
91
166
|
* {@link Exclusive.run}'s required options.
|
|
92
167
|
*
|
package/index.js
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
import { CurrentDistribution, Distribution, DistributionField, distributionSuffix, withDistribution, withDistributionVersion } from "./Distribution.js";
|
|
2
|
+
import { ErrorText } from "./ErrorText.js";
|
|
2
3
|
import { Exclusive, ExclusiveTimeout } from "./Exclusive.js";
|
|
3
4
|
import { LaunchContext } from "./LaunchContext.js";
|
|
4
5
|
import { ProcessScope, ProcessScopeError } from "./ProcessScope.js";
|
|
5
6
|
import { Remediation } from "./Remediation.js";
|
|
6
7
|
|
|
7
|
-
export { CurrentDistribution, Distribution, DistributionField, Exclusive, ExclusiveTimeout, LaunchContext, ProcessScope, ProcessScopeError, Remediation, distributionSuffix, withDistribution, withDistributionVersion };
|
|
8
|
+
export { CurrentDistribution, Distribution, DistributionField, ErrorText, Exclusive, ExclusiveTimeout, LaunchContext, ProcessScope, ProcessScopeError, Remediation, distributionSuffix, withDistribution, withDistributionVersion };
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
import { Predicate } from "effect";
|
|
2
|
+
|
|
3
|
+
// src/internal/causeMessage.ts
|
|
4
|
+
/** How many nodes of a cause chain the walk reads before stopping, so a cyclic chain cannot spin. */
|
|
5
|
+
const CAUSE_DEPTH = 8;
|
|
6
|
+
/**
|
|
7
|
+
* The message a single node carries: a thrown string, or a non-empty string `message` property. A getter or
|
|
8
|
+
* proxy trap that throws is a node with no message.
|
|
9
|
+
*/
|
|
10
|
+
const messageAt = (node) => {
|
|
11
|
+
try {
|
|
12
|
+
const text = Predicate.isString(node) ? node : Predicate.hasProperty(node, "message") && Predicate.isString(node.message) ? node.message : void 0;
|
|
13
|
+
return text === void 0 || text.trim() === "" ? void 0 : text;
|
|
14
|
+
} catch {
|
|
15
|
+
return;
|
|
16
|
+
}
|
|
17
|
+
};
|
|
18
|
+
/** The next link of the chain: a node's `cause`, or `undefined` when it has none or reading it throws. */
|
|
19
|
+
const causeAt = (node) => {
|
|
20
|
+
try {
|
|
21
|
+
return Predicate.hasProperty(node, "cause") ? node.cause : void 0;
|
|
22
|
+
} catch {
|
|
23
|
+
return;
|
|
24
|
+
}
|
|
25
|
+
};
|
|
26
|
+
/**
|
|
27
|
+
* Every distinct non-empty message a preserved cause chain carries, nearest
|
|
28
|
+
* first and joined with `: `, or `undefined` when nothing along it has one.
|
|
29
|
+
*
|
|
30
|
+
* A `Schema.Defect()` field holds whatever was thrown, so the read is guarded
|
|
31
|
+
* rather than assumed: `Predicate.hasProperty` + `Predicate.isString` accepts
|
|
32
|
+
* an `Error`, a cross-realm `Error` that fails `instanceof`, a plain
|
|
33
|
+
* `{ message }` object and a thrown string alike. An empty or whitespace-only
|
|
34
|
+
* message counts as none. The walk follows `cause` links because a wrapper's
|
|
35
|
+
* text is often the generic summary and the driver's text underneath is the
|
|
36
|
+
* actionable detail, yet a wrapper that composes its own context must not
|
|
37
|
+
* lose it either; so nothing is dropped, and a deeper text the nearer one
|
|
38
|
+
* already contains is not repeated. The walk is bounded, so a cycle terminates.
|
|
39
|
+
*
|
|
40
|
+
* It never throws: every property read is guarded, so a `message` getter that throws leaves that link
|
|
41
|
+
* without text, and a `cause` getter that throws ends the walk with what was found so far.
|
|
42
|
+
*/
|
|
43
|
+
const causeMessage = (cause) => {
|
|
44
|
+
let message;
|
|
45
|
+
let node = cause;
|
|
46
|
+
for (let depth = 0; depth < CAUSE_DEPTH && node !== void 0 && node !== null; depth++) {
|
|
47
|
+
const text = messageAt(node);
|
|
48
|
+
if (text !== void 0) {
|
|
49
|
+
if (message === void 0 || text.includes(message)) message = text;
|
|
50
|
+
else if (!message.includes(text)) message = `${message}: ${text}`;
|
|
51
|
+
}
|
|
52
|
+
node = causeAt(node);
|
|
53
|
+
}
|
|
54
|
+
return message;
|
|
55
|
+
};
|
|
56
|
+
|
|
57
|
+
export { causeMessage };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@effected/engine",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.11.0",
|
|
4
4
|
"private": false,
|
|
5
5
|
"description": "Platform-free primitives shared by every front end of an Effect v4 tool: distribution identity, remediation, launch context, and transport-neutral process crash guards",
|
|
6
6
|
"keywords": [
|
|
@@ -42,7 +42,7 @@
|
|
|
42
42
|
"./package.json": "./package.json"
|
|
43
43
|
},
|
|
44
44
|
"peerDependencies": {
|
|
45
|
-
"effect": "
|
|
45
|
+
"effect": "~4.1.0"
|
|
46
46
|
},
|
|
47
47
|
"engines": {
|
|
48
48
|
"node": ">=24.11.0"
|