@art-lib/operations 0.0.0-stage → 0.0.2

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/CHANGELOG.md ADDED
@@ -0,0 +1,7 @@
1
+ # CHANGELOG
2
+
3
+ ## 0.0.2
4
+
5
+ ### Added
6
+
7
+ - Extend the three model factories with `<D>` generics and an optional `message` hook on `createGenericOperation`.
package/LICENSE-MIT ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024 Noodlestan
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,110 @@
1
- # Temporary Holding Version
1
+ # @art-lib/operations
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > Operation outcome types and factories, and an append-only operations log that forwards every operation to the logger.
4
+
5
+ This package is part of the [Art Lib toolkit](../../README.md).
6
+
7
+ ## Design
8
+
9
+ The package defines the operation model: one unit of work in a command invocation, carrying a pending, success, or failure outcome. Factories build the pending operation and then derive the finished one from it. The package also provides a thin, append-only operations log. Created alongside a logger, it forwards every operation to that logger and keeps the finished ones queryable.
10
+
11
+ Every operation doubles as a log message for [`@art-lib/logger`](../logger/README.md). It carries a level derived from its outcome — pending logs as debug, success as info, failure as error — so the logger consumes operations directly without ever learning what they are. That logger is the package's only dependency.
12
+
13
+ See also:
14
+
15
+ - [package knowledge](knowledge/index.md) — overview, design, and decision records
16
+ - [repository design record](../../knowledge/design/operations.md) — what a CLI needs from the package
17
+
18
+ ## Usage
19
+
20
+ ### Install
21
+
22
+ ```bash
23
+ npm install @art-lib/operations
24
+ ```
25
+
26
+ `@art-lib/logger` arrives as a dependency; import it wherever you create the logger.
27
+
28
+ ### Configure
29
+
30
+ Create one operations log per command invocation, right after the logger. Every operation logged through it is forwarded to the logger, so resolve the output mode first:
31
+
32
+ ```ts
33
+ import { createLogger } from '@art-lib/logger';
34
+ import { createOperationsLog } from '@art-lib/operations/log';
35
+
36
+ const logger = createLogger();
37
+
38
+ // Buffered messages flush as soon as the mode is resolved.
39
+ logger.setOutputMode(process.env.VERBOSE ? 'verbose' : 'normal');
40
+
41
+ // One log per command invocation; discard it when the invocation ends.
42
+ export const operations = createOperationsLog(logger);
43
+ ```
44
+
45
+ The package root re-exports both subpaths, so `import { ... } from '@art-lib/operations'` works as well.
46
+
47
+ ### Example
48
+
49
+ ```ts
50
+ import {
51
+ createGenericOperation,
52
+ createOperationFailure,
53
+ createOperationSuccess,
54
+ } from '@art-lib/operations';
55
+ import { operations } from './log.js';
56
+
57
+ const startedAt = Date.now();
58
+
59
+ const pending = createGenericOperation('clone', { repo });
60
+ operations.log(pending); // forwarded as `debug`; pending operations are not stored
61
+
62
+ try {
63
+ const path = await clone(pending.data.repo);
64
+
65
+ operations.log(createOperationSuccess(pending, `cloned ${path}`)); // stored
66
+ } catch (error) {
67
+ // The label prefixes `errorSerialized()` only — `error` stays the raw message.
68
+ operations.log(createOperationFailure(pending, error, { label: 'CloneError' })); // stored
69
+ }
70
+
71
+ // The log keeps finished operations only, in order:
72
+ operations.all(); // every finished operation
73
+ operations.since(startedAt); // created at or after `startedAt`
74
+ operations.latest(5); // the last five finished operations
75
+ ```
76
+
77
+ ### Options
78
+
79
+ | Function | Arguments | Returns | Notes |
80
+ | -------------------------------------------------- | ---------------------------------------------------- | ------------------ | ------------------------------------------------------------------- |
81
+ | `createGenericOperation(name, data?, text?)` | operation name, optional payload, optional text | `OperationPending` | frozen; reports the payload as JSON by default; `timing()` is `NaN` |
82
+ | `createOperationSuccess(pending, text?)` | a pending operation, optional success text | `OperationSuccess` | falls back to the pending's own text |
83
+ | `createOperationFailure(pending, error, options?)` | a pending operation, any error-shaped value, options | `OperationFailure` | the options carry a label that prefixes `errorSerialized()` |
84
+ | `createOperationsLog(logger, options?)` | a logger, reserved options | `OperationsLog` | forwards every operation; stores finished operations only |
85
+
86
+ - **Payload** — carried on the operation untouched, from pending through to success or failure. By default the payload is serialised to JSON as the operation's text, until a success text overrides it.
87
+ - **Options** — the log accepts a second argument and deliberately ignores it; it is reserved for a future iteration.
88
+ - **Operations log** — offers `log`, `all`, `since` and `latest`. The query methods return copies, never the internal buffer.
89
+
90
+ ## Development
91
+
92
+ Make sure you read the [Art Lib README](../../README.md) first.
93
+
94
+ ### Build Targets
95
+
96
+ This package is meant for use in Node.js environments. The entry point is built using `esbuild` pre-configured by [Workspace Tooling](https://github.com/noodlestan/workspace-tooling).
97
+
98
+ ### Scripts
99
+
100
+ - **$** `npm run dev` — Watch mode for development
101
+ - **$** `npm run lint` — Check formatting, lint, and type check
102
+ - **$** `npm run lint:fix` — Fix formatting and lint issues
103
+ - **$** `npm run build` — Build the package
104
+ - **$** `npm run build:clean` — Remove build artifacts
105
+ - **$** `npm run test` — Run tests
106
+ - **$** `npm run ci` — Run CI pipeline
107
+
108
+ ## Copyright (c) 2026 [Noodlestan](https://noodlestan.org/).
109
+
110
+ Published under a [MIT license](https://noodlestan.mit-license.org/).
@@ -0,0 +1,2 @@
1
+ export * from './log/index.js';
2
+ export * from './model/index.js';
package/dist/index.mjs ADDED
@@ -0,0 +1,141 @@
1
+ // src/log/private/isFinished.ts
2
+ function isFinished(operation) {
3
+ return operation.outcome !== "pending";
4
+ }
5
+
6
+ // src/log/createOperationsLog.ts
7
+ function createOperationsLog(logger, options) {
8
+ void options;
9
+ const storedOperations = [];
10
+ return {
11
+ log(operation) {
12
+ logger.log(operation);
13
+ if (isFinished(operation)) {
14
+ storedOperations.push(operation);
15
+ }
16
+ },
17
+ all() {
18
+ return [...storedOperations];
19
+ },
20
+ since(timestamp) {
21
+ return storedOperations.filter((operation) => operation.ts >= timestamp);
22
+ },
23
+ latest(count) {
24
+ if (count <= 0) {
25
+ return [];
26
+ }
27
+ return storedOperations.slice(Math.max(storedOperations.length - count, 0));
28
+ }
29
+ };
30
+ }
31
+
32
+ // src/model/private/constants.ts
33
+ var LEVELS = {
34
+ pending: "debug",
35
+ success: "info",
36
+ failure: "error"
37
+ };
38
+
39
+ // src/model/private/formatData.ts
40
+ function formatData(data) {
41
+ return data ? JSON.stringify(data) : "";
42
+ }
43
+
44
+ // src/model/createGenericOperation.ts
45
+ function createGenericOperation(name, data, toText) {
46
+ const ts = Date.now();
47
+ const resolveToText = toText ?? formatData;
48
+ function readText() {
49
+ return resolveToText(data);
50
+ }
51
+ const pending = {
52
+ operation: name,
53
+ ts,
54
+ outcome: "pending",
55
+ level: LEVELS.pending,
56
+ data,
57
+ text: readText,
58
+ timing() {
59
+ return Number.NaN;
60
+ }
61
+ };
62
+ return Object.freeze(pending);
63
+ }
64
+
65
+ // src/model/private/readRawErrorMessage.ts
66
+ function readRawErrorMessage(error) {
67
+ if (typeof error === "string") {
68
+ return error;
69
+ }
70
+ if (error === null || error === void 0) {
71
+ return "";
72
+ }
73
+ if (typeof error === "object" && "message" in error) {
74
+ const { message } = error;
75
+ if (typeof message === "string") {
76
+ return message;
77
+ }
78
+ }
79
+ try {
80
+ return String(error);
81
+ } catch {
82
+ return "";
83
+ }
84
+ }
85
+
86
+ // src/model/createOperationFailure.ts
87
+ function createOperationFailure(pending, error, options) {
88
+ const finishedTs = Date.now();
89
+ const rawError = readRawErrorMessage(error);
90
+ const label = options?.label;
91
+ function report() {
92
+ return rawError;
93
+ }
94
+ function errorSerialized() {
95
+ return label ? `${label}: ${rawError}` : rawError;
96
+ }
97
+ const failure = {
98
+ operation: pending.operation,
99
+ ts: pending.ts,
100
+ finishedTs,
101
+ outcome: "failure",
102
+ level: LEVELS.failure,
103
+ data: pending.data,
104
+ error: rawError,
105
+ text: report,
106
+ timing() {
107
+ return finishedTs - pending.ts;
108
+ },
109
+ errorSerialized
110
+ };
111
+ return Object.freeze(failure);
112
+ }
113
+
114
+ // src/model/createOperationSuccess.ts
115
+ function createOperationSuccess(pending, text) {
116
+ const finishedTs = Date.now();
117
+ const givenText = text ?? pending.text();
118
+ function report() {
119
+ return givenText;
120
+ }
121
+ const success = {
122
+ operation: pending.operation,
123
+ ts: pending.ts,
124
+ finishedTs,
125
+ outcome: "success",
126
+ level: LEVELS.success,
127
+ data: pending.data,
128
+ text: report,
129
+ timing() {
130
+ return finishedTs - pending.ts;
131
+ }
132
+ };
133
+ return Object.freeze(success);
134
+ }
135
+ export {
136
+ createGenericOperation,
137
+ createOperationFailure,
138
+ createOperationSuccess,
139
+ createOperationsLog
140
+ };
141
+ //# sourceMappingURL=index.mjs.map
@@ -0,0 +1,7 @@
1
+ {
2
+ "version": 3,
3
+ "sources": ["../src/log/private/isFinished.ts", "../src/log/createOperationsLog.ts", "../src/model/private/constants.ts", "../src/model/private/formatData.ts", "../src/model/createGenericOperation.ts", "../src/model/private/readRawErrorMessage.ts", "../src/model/createOperationFailure.ts", "../src/model/createOperationSuccess.ts"],
4
+ "sourcesContent": ["import type { AnyFinishedOperation, LoggableOperation } from '../types.js';\n\nexport function isFinished(operation: LoggableOperation): operation is AnyFinishedOperation {\n\treturn operation.outcome !== 'pending';\n}\n", "import { isFinished } from './private/isFinished.js';\nimport type {\n\tAnyFinishedOperation,\n\tLoggerInterface,\n\tOperationsLog,\n\tOperationsLogOptions,\n} from './types.js';\n\nexport function createOperationsLog(\n\tlogger: LoggerInterface,\n\toptions?: OperationsLogOptions,\n): OperationsLog {\n\t// Reserved for a future iteration: accepted, deliberately not read here.\n\t// eslint-disable-next-line no-void\n\tvoid options;\n\n\tconst storedOperations: AnyFinishedOperation[] = [];\n\n\treturn {\n\t\tlog(operation): void {\n\t\t\tlogger.log(operation); // every operation is a message: pending and finished alike\n\n\t\t\tif (isFinished(operation)) {\n\t\t\t\tstoredOperations.push(operation); // finished operations only\n\t\t\t}\n\t\t},\n\t\tall(): AnyFinishedOperation[] {\n\t\t\treturn [...storedOperations]; // a copy \u2014 never leak the internal buffer\n\t\t},\n\t\tsince(timestamp: number): AnyFinishedOperation[] {\n\t\t\treturn storedOperations.filter(operation => operation.ts >= timestamp);\n\t\t},\n\t\tlatest(count: number): AnyFinishedOperation[] {\n\t\t\tif (count <= 0) {\n\t\t\t\treturn [];\n\t\t\t}\n\n\t\t\treturn storedOperations.slice(Math.max(storedOperations.length - count, 0));\n\t\t},\n\t};\n}\n", "import type { MessageLevel } from '@art-lib/logger';\n\nimport type { OperationOutcome } from '../types.js';\n\nexport const LEVELS: Record<OperationOutcome, MessageLevel> = {\n\tpending: 'debug',\n\tsuccess: 'info',\n\tfailure: 'error',\n};\n", "export function formatData(data: unknown): string {\n\treturn data ? JSON.stringify(data) : '';\n}\n", "import { LEVELS } from './private/constants.js';\nimport { formatData } from './private/formatData.js';\nimport type { OperationPending } from './types.js';\n\nexport function createGenericOperation<N extends string, D = unknown>(\n\tname: N,\n\tdata?: D,\n\ttoText?: (data: D) => string,\n): OperationPending<D> & { operation: N } {\n\tconst ts = Date.now();\n\tconst resolveToText: (value: D) => string = toText ?? formatData;\n\n\tfunction readText(): string {\n\t\treturn resolveToText(data as D);\n\t}\n\n\tconst pending: OperationPending<D> = {\n\t\toperation: name,\n\t\tts,\n\t\toutcome: 'pending',\n\t\tlevel: LEVELS.pending,\n\t\tdata,\n\t\ttext: readText,\n\t\ttiming(): number {\n\t\t\treturn Number.NaN;\n\t\t},\n\t};\n\n\treturn Object.freeze(pending) as OperationPending<D> & { operation: N };\n}\n", "export function readRawErrorMessage(error: unknown): string {\n\tif (typeof error === 'string') {\n\t\treturn error;\n\t}\n\n\tif (error === null || error === undefined) {\n\t\treturn '';\n\t}\n\n\tif (typeof error === 'object' && 'message' in error) {\n\t\tconst { message } = error as { message: unknown };\n\n\t\tif (typeof message === 'string') {\n\t\t\treturn message;\n\t\t}\n\t}\n\n\ttry {\n\t\treturn String(error);\n\t} catch {\n\t\treturn '';\n\t}\n}\n", "import { LEVELS } from './private/constants.js';\nimport { readRawErrorMessage } from './private/readRawErrorMessage.js';\nimport type { OperationFailure, OperationPending } from './types.js';\n\nexport function createOperationFailure<D>(\n\tpending: OperationPending<D>,\n\terror: unknown,\n\toptions?: { label?: string },\n): OperationFailure<D> {\n\tconst finishedTs = Date.now();\n\tconst rawError = readRawErrorMessage(error);\n\tconst label = options?.label;\n\n\tfunction report(): string {\n\t\treturn rawError;\n\t}\n\n\tfunction errorSerialized(): string {\n\t\treturn label ? `${label}: ${rawError}` : rawError;\n\t}\n\n\tconst failure: OperationFailure<D> = {\n\t\toperation: pending.operation,\n\t\tts: pending.ts,\n\t\tfinishedTs,\n\t\toutcome: 'failure',\n\t\tlevel: LEVELS.failure,\n\t\tdata: pending.data,\n\t\terror: rawError,\n\t\ttext: report,\n\t\ttiming(): number {\n\t\t\treturn finishedTs - pending.ts;\n\t\t},\n\t\terrorSerialized,\n\t};\n\n\treturn Object.freeze(failure);\n}\n", "import { LEVELS } from './private/constants.js';\nimport type { OperationPending, OperationSuccess } from './types.js';\n\nexport function createOperationSuccess<D>(\n\tpending: OperationPending<D>,\n\ttext?: string,\n): OperationSuccess<D> {\n\tconst finishedTs = Date.now();\n\tconst givenText = text ?? pending.text();\n\n\tfunction report(): string {\n\t\treturn givenText;\n\t}\n\n\tconst success: OperationSuccess<D> = {\n\t\toperation: pending.operation,\n\t\tts: pending.ts,\n\t\tfinishedTs,\n\t\toutcome: 'success',\n\t\tlevel: LEVELS.success,\n\t\tdata: pending.data,\n\t\ttext: report,\n\t\ttiming(): number {\n\t\t\treturn finishedTs - pending.ts;\n\t\t},\n\t};\n\n\treturn Object.freeze(success);\n}\n"],
5
+ "mappings": "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",
6
+ "names": []
7
+ }
@@ -0,0 +1,2 @@
1
+ import type { LoggerInterface, OperationsLog, OperationsLogOptions } from './types.js';
2
+ export declare function createOperationsLog(logger: LoggerInterface, options?: OperationsLogOptions): OperationsLog;
@@ -0,0 +1,2 @@
1
+ export { createOperationsLog } from './createOperationsLog.js';
2
+ export type { AnyFinishedOperation, LoggableOperation, OperationsLog, OperationsLogOptions, } from './types.js';
@@ -0,0 +1,34 @@
1
+ // src/log/private/isFinished.ts
2
+ function isFinished(operation) {
3
+ return operation.outcome !== "pending";
4
+ }
5
+
6
+ // src/log/createOperationsLog.ts
7
+ function createOperationsLog(logger, options) {
8
+ void options;
9
+ const storedOperations = [];
10
+ return {
11
+ log(operation) {
12
+ logger.log(operation);
13
+ if (isFinished(operation)) {
14
+ storedOperations.push(operation);
15
+ }
16
+ },
17
+ all() {
18
+ return [...storedOperations];
19
+ },
20
+ since(timestamp) {
21
+ return storedOperations.filter((operation) => operation.ts >= timestamp);
22
+ },
23
+ latest(count) {
24
+ if (count <= 0) {
25
+ return [];
26
+ }
27
+ return storedOperations.slice(Math.max(storedOperations.length - count, 0));
28
+ }
29
+ };
30
+ }
31
+ export {
32
+ createOperationsLog
33
+ };
34
+ //# sourceMappingURL=index.mjs.map
@@ -0,0 +1,7 @@
1
+ {
2
+ "version": 3,
3
+ "sources": ["../../src/log/private/isFinished.ts", "../../src/log/createOperationsLog.ts"],
4
+ "sourcesContent": ["import type { AnyFinishedOperation, LoggableOperation } from '../types.js';\n\nexport function isFinished(operation: LoggableOperation): operation is AnyFinishedOperation {\n\treturn operation.outcome !== 'pending';\n}\n", "import { isFinished } from './private/isFinished.js';\nimport type {\n\tAnyFinishedOperation,\n\tLoggerInterface,\n\tOperationsLog,\n\tOperationsLogOptions,\n} from './types.js';\n\nexport function createOperationsLog(\n\tlogger: LoggerInterface,\n\toptions?: OperationsLogOptions,\n): OperationsLog {\n\t// Reserved for a future iteration: accepted, deliberately not read here.\n\t// eslint-disable-next-line no-void\n\tvoid options;\n\n\tconst storedOperations: AnyFinishedOperation[] = [];\n\n\treturn {\n\t\tlog(operation): void {\n\t\t\tlogger.log(operation); // every operation is a message: pending and finished alike\n\n\t\t\tif (isFinished(operation)) {\n\t\t\t\tstoredOperations.push(operation); // finished operations only\n\t\t\t}\n\t\t},\n\t\tall(): AnyFinishedOperation[] {\n\t\t\treturn [...storedOperations]; // a copy \u2014 never leak the internal buffer\n\t\t},\n\t\tsince(timestamp: number): AnyFinishedOperation[] {\n\t\t\treturn storedOperations.filter(operation => operation.ts >= timestamp);\n\t\t},\n\t\tlatest(count: number): AnyFinishedOperation[] {\n\t\t\tif (count <= 0) {\n\t\t\t\treturn [];\n\t\t\t}\n\n\t\t\treturn storedOperations.slice(Math.max(storedOperations.length - count, 0));\n\t\t},\n\t};\n}\n"],
5
+ "mappings": ";AAEO,SAAS,WAAW,WAAiE;AAC3F,SAAO,UAAU,YAAY;AAC9B;;;ACIO,SAAS,oBACf,QACA,SACgB;AAGhB,OAAK;AAEL,QAAM,mBAA2C,CAAC;AAElD,SAAO;AAAA,IACN,IAAI,WAAiB;AACpB,aAAO,IAAI,SAAS;AAEpB,UAAI,WAAW,SAAS,GAAG;AAC1B,yBAAiB,KAAK,SAAS;AAAA,MAChC;AAAA,IACD;AAAA,IACA,MAA8B;AAC7B,aAAO,CAAC,GAAG,gBAAgB;AAAA,IAC5B;AAAA,IACA,MAAM,WAA2C;AAChD,aAAO,iBAAiB,OAAO,eAAa,UAAU,MAAM,SAAS;AAAA,IACtE;AAAA,IACA,OAAO,OAAuC;AAC7C,UAAI,SAAS,GAAG;AACf,eAAO,CAAC;AAAA,MACT;AAEA,aAAO,iBAAiB,MAAM,KAAK,IAAI,iBAAiB,SAAS,OAAO,CAAC,CAAC;AAAA,IAC3E;AAAA,EACD;AACD;",
6
+ "names": []
7
+ }
@@ -0,0 +1,2 @@
1
+ import type { AnyFinishedOperation, LoggableOperation } from '../types.js';
2
+ export declare function isFinished(operation: LoggableOperation): operation is AnyFinishedOperation;
@@ -0,0 +1,16 @@
1
+ import type { Message } from '@art-lib/logger';
2
+ import type { OperationFailure, OperationSuccess } from '../model/index.js';
3
+ export type AnyFinishedOperation = OperationSuccess | OperationFailure;
4
+ export type LoggableOperation = Message & {
5
+ outcome: string;
6
+ };
7
+ export type OperationsLog = {
8
+ log(operation: LoggableOperation): void;
9
+ all(): AnyFinishedOperation[];
10
+ since(timestamp: number): AnyFinishedOperation[];
11
+ latest(count: number): AnyFinishedOperation[];
12
+ };
13
+ export type LoggerInterface = {
14
+ log(operation: LoggableOperation): void;
15
+ };
16
+ export type OperationsLogOptions = unknown;
@@ -0,0 +1,4 @@
1
+ import type { OperationPending } from './types.js';
2
+ export declare function createGenericOperation<N extends string, D = unknown>(name: N, data?: D, toText?: (data: D) => string): OperationPending<D> & {
3
+ operation: N;
4
+ };
@@ -0,0 +1,4 @@
1
+ import type { OperationFailure, OperationPending } from './types.js';
2
+ export declare function createOperationFailure<D>(pending: OperationPending<D>, error: unknown, options?: {
3
+ label?: string;
4
+ }): OperationFailure<D>;
@@ -0,0 +1,2 @@
1
+ import type { OperationPending, OperationSuccess } from './types.js';
2
+ export declare function createOperationSuccess<D>(pending: OperationPending<D>, text?: string): OperationSuccess<D>;
@@ -0,0 +1,4 @@
1
+ export type { OperationBase, OperationFailure, OperationOutcome, OperationPending, OperationSuccess, } from './types.js';
2
+ export { createGenericOperation } from './createGenericOperation.js';
3
+ export { createOperationFailure } from './createOperationFailure.js';
4
+ export { createOperationSuccess } from './createOperationSuccess.js';
@@ -0,0 +1,109 @@
1
+ // src/model/private/constants.ts
2
+ var LEVELS = {
3
+ pending: "debug",
4
+ success: "info",
5
+ failure: "error"
6
+ };
7
+
8
+ // src/model/private/formatData.ts
9
+ function formatData(data) {
10
+ return data ? JSON.stringify(data) : "";
11
+ }
12
+
13
+ // src/model/createGenericOperation.ts
14
+ function createGenericOperation(name, data, toText) {
15
+ const ts = Date.now();
16
+ const resolveToText = toText ?? formatData;
17
+ function readText() {
18
+ return resolveToText(data);
19
+ }
20
+ const pending = {
21
+ operation: name,
22
+ ts,
23
+ outcome: "pending",
24
+ level: LEVELS.pending,
25
+ data,
26
+ text: readText,
27
+ timing() {
28
+ return Number.NaN;
29
+ }
30
+ };
31
+ return Object.freeze(pending);
32
+ }
33
+
34
+ // src/model/private/readRawErrorMessage.ts
35
+ function readRawErrorMessage(error) {
36
+ if (typeof error === "string") {
37
+ return error;
38
+ }
39
+ if (error === null || error === void 0) {
40
+ return "";
41
+ }
42
+ if (typeof error === "object" && "message" in error) {
43
+ const { message } = error;
44
+ if (typeof message === "string") {
45
+ return message;
46
+ }
47
+ }
48
+ try {
49
+ return String(error);
50
+ } catch {
51
+ return "";
52
+ }
53
+ }
54
+
55
+ // src/model/createOperationFailure.ts
56
+ function createOperationFailure(pending, error, options) {
57
+ const finishedTs = Date.now();
58
+ const rawError = readRawErrorMessage(error);
59
+ const label = options?.label;
60
+ function report() {
61
+ return rawError;
62
+ }
63
+ function errorSerialized() {
64
+ return label ? `${label}: ${rawError}` : rawError;
65
+ }
66
+ const failure = {
67
+ operation: pending.operation,
68
+ ts: pending.ts,
69
+ finishedTs,
70
+ outcome: "failure",
71
+ level: LEVELS.failure,
72
+ data: pending.data,
73
+ error: rawError,
74
+ text: report,
75
+ timing() {
76
+ return finishedTs - pending.ts;
77
+ },
78
+ errorSerialized
79
+ };
80
+ return Object.freeze(failure);
81
+ }
82
+
83
+ // src/model/createOperationSuccess.ts
84
+ function createOperationSuccess(pending, text) {
85
+ const finishedTs = Date.now();
86
+ const givenText = text ?? pending.text();
87
+ function report() {
88
+ return givenText;
89
+ }
90
+ const success = {
91
+ operation: pending.operation,
92
+ ts: pending.ts,
93
+ finishedTs,
94
+ outcome: "success",
95
+ level: LEVELS.success,
96
+ data: pending.data,
97
+ text: report,
98
+ timing() {
99
+ return finishedTs - pending.ts;
100
+ }
101
+ };
102
+ return Object.freeze(success);
103
+ }
104
+ export {
105
+ createGenericOperation,
106
+ createOperationFailure,
107
+ createOperationSuccess
108
+ };
109
+ //# sourceMappingURL=index.mjs.map
@@ -0,0 +1,7 @@
1
+ {
2
+ "version": 3,
3
+ "sources": ["../../src/model/private/constants.ts", "../../src/model/private/formatData.ts", "../../src/model/createGenericOperation.ts", "../../src/model/private/readRawErrorMessage.ts", "../../src/model/createOperationFailure.ts", "../../src/model/createOperationSuccess.ts"],
4
+ "sourcesContent": ["import type { MessageLevel } from '@art-lib/logger';\n\nimport type { OperationOutcome } from '../types.js';\n\nexport const LEVELS: Record<OperationOutcome, MessageLevel> = {\n\tpending: 'debug',\n\tsuccess: 'info',\n\tfailure: 'error',\n};\n", "export function formatData(data: unknown): string {\n\treturn data ? JSON.stringify(data) : '';\n}\n", "import { LEVELS } from './private/constants.js';\nimport { formatData } from './private/formatData.js';\nimport type { OperationPending } from './types.js';\n\nexport function createGenericOperation<N extends string, D = unknown>(\n\tname: N,\n\tdata?: D,\n\ttoText?: (data: D) => string,\n): OperationPending<D> & { operation: N } {\n\tconst ts = Date.now();\n\tconst resolveToText: (value: D) => string = toText ?? formatData;\n\n\tfunction readText(): string {\n\t\treturn resolveToText(data as D);\n\t}\n\n\tconst pending: OperationPending<D> = {\n\t\toperation: name,\n\t\tts,\n\t\toutcome: 'pending',\n\t\tlevel: LEVELS.pending,\n\t\tdata,\n\t\ttext: readText,\n\t\ttiming(): number {\n\t\t\treturn Number.NaN;\n\t\t},\n\t};\n\n\treturn Object.freeze(pending) as OperationPending<D> & { operation: N };\n}\n", "export function readRawErrorMessage(error: unknown): string {\n\tif (typeof error === 'string') {\n\t\treturn error;\n\t}\n\n\tif (error === null || error === undefined) {\n\t\treturn '';\n\t}\n\n\tif (typeof error === 'object' && 'message' in error) {\n\t\tconst { message } = error as { message: unknown };\n\n\t\tif (typeof message === 'string') {\n\t\t\treturn message;\n\t\t}\n\t}\n\n\ttry {\n\t\treturn String(error);\n\t} catch {\n\t\treturn '';\n\t}\n}\n", "import { LEVELS } from './private/constants.js';\nimport { readRawErrorMessage } from './private/readRawErrorMessage.js';\nimport type { OperationFailure, OperationPending } from './types.js';\n\nexport function createOperationFailure<D>(\n\tpending: OperationPending<D>,\n\terror: unknown,\n\toptions?: { label?: string },\n): OperationFailure<D> {\n\tconst finishedTs = Date.now();\n\tconst rawError = readRawErrorMessage(error);\n\tconst label = options?.label;\n\n\tfunction report(): string {\n\t\treturn rawError;\n\t}\n\n\tfunction errorSerialized(): string {\n\t\treturn label ? `${label}: ${rawError}` : rawError;\n\t}\n\n\tconst failure: OperationFailure<D> = {\n\t\toperation: pending.operation,\n\t\tts: pending.ts,\n\t\tfinishedTs,\n\t\toutcome: 'failure',\n\t\tlevel: LEVELS.failure,\n\t\tdata: pending.data,\n\t\terror: rawError,\n\t\ttext: report,\n\t\ttiming(): number {\n\t\t\treturn finishedTs - pending.ts;\n\t\t},\n\t\terrorSerialized,\n\t};\n\n\treturn Object.freeze(failure);\n}\n", "import { LEVELS } from './private/constants.js';\nimport type { OperationPending, OperationSuccess } from './types.js';\n\nexport function createOperationSuccess<D>(\n\tpending: OperationPending<D>,\n\ttext?: string,\n): OperationSuccess<D> {\n\tconst finishedTs = Date.now();\n\tconst givenText = text ?? pending.text();\n\n\tfunction report(): string {\n\t\treturn givenText;\n\t}\n\n\tconst success: OperationSuccess<D> = {\n\t\toperation: pending.operation,\n\t\tts: pending.ts,\n\t\tfinishedTs,\n\t\toutcome: 'success',\n\t\tlevel: LEVELS.success,\n\t\tdata: pending.data,\n\t\ttext: report,\n\t\ttiming(): number {\n\t\t\treturn finishedTs - pending.ts;\n\t\t},\n\t};\n\n\treturn Object.freeze(success);\n}\n"],
5
+ "mappings": ";AAIO,IAAM,SAAiD;AAAA,EAC7D,SAAS;AAAA,EACT,SAAS;AAAA,EACT,SAAS;AACV;;;ACRO,SAAS,WAAW,MAAuB;AACjD,SAAO,OAAO,KAAK,UAAU,IAAI,IAAI;AACtC;;;ACEO,SAAS,uBACf,MACA,MACA,QACyC;AACzC,QAAM,KAAK,KAAK,IAAI;AACpB,QAAM,gBAAsC,UAAU;AAEtD,WAAS,WAAmB;AAC3B,WAAO,cAAc,IAAS;AAAA,EAC/B;AAEA,QAAM,UAA+B;AAAA,IACpC,WAAW;AAAA,IACX;AAAA,IACA,SAAS;AAAA,IACT,OAAO,OAAO;AAAA,IACd;AAAA,IACA,MAAM;AAAA,IACN,SAAiB;AAChB,aAAO,OAAO;AAAA,IACf;AAAA,EACD;AAEA,SAAO,OAAO,OAAO,OAAO;AAC7B;;;AC7BO,SAAS,oBAAoB,OAAwB;AAC3D,MAAI,OAAO,UAAU,UAAU;AAC9B,WAAO;AAAA,EACR;AAEA,MAAI,UAAU,QAAQ,UAAU,QAAW;AAC1C,WAAO;AAAA,EACR;AAEA,MAAI,OAAO,UAAU,YAAY,aAAa,OAAO;AACpD,UAAM,EAAE,QAAQ,IAAI;AAEpB,QAAI,OAAO,YAAY,UAAU;AAChC,aAAO;AAAA,IACR;AAAA,EACD;AAEA,MAAI;AACH,WAAO,OAAO,KAAK;AAAA,EACpB,QAAQ;AACP,WAAO;AAAA,EACR;AACD;;;AClBO,SAAS,uBACf,SACA,OACA,SACsB;AACtB,QAAM,aAAa,KAAK,IAAI;AAC5B,QAAM,WAAW,oBAAoB,KAAK;AAC1C,QAAM,QAAQ,SAAS;AAEvB,WAAS,SAAiB;AACzB,WAAO;AAAA,EACR;AAEA,WAAS,kBAA0B;AAClC,WAAO,QAAQ,GAAG,KAAK,KAAK,QAAQ,KAAK;AAAA,EAC1C;AAEA,QAAM,UAA+B;AAAA,IACpC,WAAW,QAAQ;AAAA,IACnB,IAAI,QAAQ;AAAA,IACZ;AAAA,IACA,SAAS;AAAA,IACT,OAAO,OAAO;AAAA,IACd,MAAM,QAAQ;AAAA,IACd,OAAO;AAAA,IACP,MAAM;AAAA,IACN,SAAiB;AAChB,aAAO,aAAa,QAAQ;AAAA,IAC7B;AAAA,IACA;AAAA,EACD;AAEA,SAAO,OAAO,OAAO,OAAO;AAC7B;;;AClCO,SAAS,uBACf,SACA,MACsB;AACtB,QAAM,aAAa,KAAK,IAAI;AAC5B,QAAM,YAAY,QAAQ,QAAQ,KAAK;AAEvC,WAAS,SAAiB;AACzB,WAAO;AAAA,EACR;AAEA,QAAM,UAA+B;AAAA,IACpC,WAAW,QAAQ;AAAA,IACnB,IAAI,QAAQ;AAAA,IACZ;AAAA,IACA,SAAS;AAAA,IACT,OAAO,OAAO;AAAA,IACd,MAAM,QAAQ;AAAA,IACd,MAAM;AAAA,IACN,SAAiB;AAChB,aAAO,aAAa,QAAQ;AAAA,IAC7B;AAAA,EACD;AAEA,SAAO,OAAO,OAAO,OAAO;AAC7B;",
6
+ "names": []
7
+ }
@@ -0,0 +1,3 @@
1
+ import type { MessageLevel } from '@art-lib/logger';
2
+ import type { OperationOutcome } from '../types.js';
3
+ export declare const LEVELS: Record<OperationOutcome, MessageLevel>;
@@ -0,0 +1 @@
1
+ export declare function formatData(data: unknown): string;
@@ -0,0 +1 @@
1
+ export declare function readRawErrorMessage(error: unknown): string;
@@ -0,0 +1,25 @@
1
+ import type { MessageLevel } from '@art-lib/logger';
2
+ export type OperationOutcome = 'pending' | 'success' | 'failure';
3
+ export type OperationBase = {
4
+ readonly operation: string;
5
+ readonly ts: number;
6
+ readonly finishedTs?: number;
7
+ readonly outcome: OperationOutcome;
8
+ text(): string;
9
+ timing(): number;
10
+ readonly level: MessageLevel;
11
+ };
12
+ export type OperationPending<D = unknown> = OperationBase & {
13
+ readonly outcome: 'pending';
14
+ readonly data?: D;
15
+ };
16
+ export type OperationSuccess<D = unknown> = OperationBase & {
17
+ readonly outcome: 'success';
18
+ readonly data?: D;
19
+ };
20
+ export type OperationFailure<D = unknown> = OperationBase & {
21
+ readonly outcome: 'failure';
22
+ readonly data?: D;
23
+ readonly error: string;
24
+ errorSerialized(): string;
25
+ };
@@ -0,0 +1,3 @@
1
+ import type { LoggerMock } from './types.js';
2
+ /** @mocks the logger the operations log forwards to */
3
+ export declare function createLoggerMock(): LoggerMock;
@@ -0,0 +1,5 @@
1
+ import type { LoggableOperation, LoggerInterface } from '../../../log/types.js';
2
+ export type LoggerMock = {
3
+ logger: LoggerInterface;
4
+ messages: LoggableOperation[];
5
+ };
package/package.json CHANGED
@@ -1,6 +1,64 @@
1
1
  {
2
2
  "name": "@art-lib/operations",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.0.2",
4
+ "description": "Operation outcome types and factories, and an append-only operations log that forwards every operation to the logger.",
5
+ "keywords": [
6
+ "library",
7
+ "operations",
8
+ "cli",
9
+ "tooling",
10
+ "art",
11
+ "terminal-apps"
12
+ ],
13
+ "author": "Noodlestan Collective",
14
+ "license": "MIT",
15
+ "repository": {
16
+ "type": "git",
17
+ "url": "https://github.com/noodlestan/art-lib.git",
18
+ "directory": "libs/operations"
19
+ },
20
+ "private": false,
21
+ "publishConfig": {
22
+ "access": "public"
23
+ },
24
+ "files": [
25
+ "dist",
26
+ "README.md",
27
+ "LICENSE-MIT",
28
+ "CHANGELOG.md"
29
+ ],
30
+ "engines": {
31
+ "node": ">=22"
32
+ },
33
+ "type": "module",
34
+ "sideEffects": false,
35
+ "exports": {
36
+ ".": {
37
+ "types": "./dist/index.d.ts",
38
+ "import": "./dist/index.mjs"
39
+ },
40
+ "./model": {
41
+ "types": "./dist/model/index.d.ts",
42
+ "import": "./dist/model/index.mjs"
43
+ },
44
+ "./log": {
45
+ "types": "./dist/log/index.d.ts",
46
+ "import": "./dist/log/index.mjs"
47
+ }
48
+ },
49
+ "scripts": {
50
+ "dev": "esbuild-cli-watch",
51
+ "lint": "prettier . -c && eslint . && tsc --noEmit",
52
+ "lint:fix": "prettier . -c --write && eslint . --fix",
53
+ "build": "esbuild-cli",
54
+ "build:clean": "rm -rf dist",
55
+ "test": "vitest run",
56
+ "test:ci": "vitest run --coverage",
57
+ "test:watch": "vitest",
58
+ "ci": "npm run lint && npm run build && npm run test:ci"
59
+ },
60
+ "dependencies": {
61
+ "@art-lib/logger": "0.0.1"
62
+ },
63
+ "devDependencies": {}
64
+ }