@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 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` `^4.0.0`) and still in `0.x` development. Stable 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-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
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.9.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": "^4.0.0"
45
+ "effect": "~4.1.0"
46
46
  },
47
47
  "engines": {
48
48
  "node": ">=24.11.0"
@@ -5,7 +5,7 @@
5
5
  "toolPackages": [
6
6
  {
7
7
  "packageName": "@microsoft/api-extractor",
8
- "packageVersion": "7.59.4"
8
+ "packageVersion": "7.60.0"
9
9
  }
10
10
  ]
11
11
  }