@mxpicture/gcp-functions-fs 1.1.3 → 1.1.5
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/config/ConfigJson.d.ts +39 -0
- package/dist/config/ConfigJson.d.ts.map +1 -1
- package/dist/config/ConfigJson.js +38 -0
- package/dist/config/ConfigJson.js.map +1 -1
- package/dist/history/HistoryJson.d.ts +68 -0
- package/dist/history/HistoryJson.d.ts.map +1 -1
- package/dist/history/HistoryJson.js +59 -0
- package/dist/history/HistoryJson.js.map +1 -1
- package/package.json +5 -3
|
@@ -1,15 +1,54 @@
|
|
|
1
1
|
import { z } from "zod";
|
|
2
|
+
/** Base type for configuration content stored as a JSON object. */
|
|
2
3
|
export type ConfigContent = Record<string, unknown>;
|
|
4
|
+
/**
|
|
5
|
+
* Manages reading, writing, and validating a JSON5 configuration file.
|
|
6
|
+
*
|
|
7
|
+
* @remarks
|
|
8
|
+
* Content is validated against a Zod schema derived from the provided shape.
|
|
9
|
+
* The configuration directory is created automatically on {@link write} if it does not exist.
|
|
10
|
+
*
|
|
11
|
+
* @typeParam T - The shape of the configuration content.
|
|
12
|
+
*/
|
|
3
13
|
export declare class ConfigJson<T extends ConfigContent> {
|
|
4
14
|
readonly path: string;
|
|
5
15
|
readonly shape: z.ZodRawShape;
|
|
16
|
+
/** Absolute path to the directory containing the configuration file. */
|
|
6
17
|
readonly configDir: string;
|
|
7
18
|
protected _schema: z.ZodObject | null;
|
|
8
19
|
protected _content: T | null;
|
|
20
|
+
/**
|
|
21
|
+
* Creates a new configuration wrapper.
|
|
22
|
+
*
|
|
23
|
+
* @param path - Absolute path to the JSON5 configuration file.
|
|
24
|
+
* @param shape - Zod raw shape used to build the validation schema.
|
|
25
|
+
*/
|
|
9
26
|
constructor(path: string, shape: z.ZodRawShape);
|
|
27
|
+
/**
|
|
28
|
+
* Returns the validated configuration content.
|
|
29
|
+
*
|
|
30
|
+
* @throws Error if the content has not been loaded or set.
|
|
31
|
+
*/
|
|
10
32
|
get content(): T;
|
|
33
|
+
/**
|
|
34
|
+
* Sets the configuration content after synchronous validation.
|
|
35
|
+
*
|
|
36
|
+
* @param data - The configuration data to set.
|
|
37
|
+
*/
|
|
11
38
|
set content(data: T);
|
|
39
|
+
/**
|
|
40
|
+
* Reads and validates the configuration file from disk.
|
|
41
|
+
*
|
|
42
|
+
* @remarks
|
|
43
|
+
* The file is parsed as JSON5 and validated against the schema.
|
|
44
|
+
*/
|
|
12
45
|
read(): Promise<void>;
|
|
46
|
+
/**
|
|
47
|
+
* Validates the current content and writes it to disk as formatted JSON.
|
|
48
|
+
*
|
|
49
|
+
* @remarks
|
|
50
|
+
* Creates the configuration directory recursively if it does not exist.
|
|
51
|
+
*/
|
|
13
52
|
write(): Promise<void>;
|
|
14
53
|
protected schema(): z.ZodObject<z.core.$ZodLooseShape, z.core.$strip>;
|
|
15
54
|
protected validate(content: Partial<T>): Promise<T>;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ConfigJson.d.ts","sourceRoot":"","sources":["../../src/config/ConfigJson.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD,qBAAa,UAAU,CAAC,CAAC,SAAS,aAAa;
|
|
1
|
+
{"version":3,"file":"ConfigJson.d.ts","sourceRoot":"","sources":["../../src/config/ConfigJson.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,mEAAmE;AACnE,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD;;;;;;;;GAQG;AACH,qBAAa,UAAU,CAAC,CAAC,SAAS,aAAa;aAa3B,IAAI,EAAE,MAAM;aACZ,KAAK,EAAE,CAAC,CAAC,WAAW;IAbtC,wEAAwE;IACxE,SAAgB,SAAS,EAAE,MAAM,CAAC;IAClC,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,SAAS,GAAG,IAAI,CAAQ;IAC7C,SAAS,CAAC,QAAQ,EAAE,CAAC,GAAG,IAAI,CAAQ;IAEpC;;;;;OAKG;gBAEe,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,CAAC,CAAC,WAAW;IAKtC;;;;OAIG;IACH,IAAW,OAAO,IAAI,CAAC,CAGtB;IAED;;;;OAIG;IACH,IAAW,OAAO,CAAC,IAAI,EAAE,CAAC,EAEzB;IAED;;;;;OAKG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAMlC;;;;;OAKG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IASnC,SAAS,CAAC,MAAM;cAKA,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAIzD,SAAS,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;CAG/C"}
|
|
@@ -3,28 +3,66 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
|
|
|
3
3
|
import { z } from "zod";
|
|
4
4
|
import pkg from "json5";
|
|
5
5
|
import { formatJson } from "@mxpicture/build-api/code";
|
|
6
|
+
/**
|
|
7
|
+
* Manages reading, writing, and validating a JSON5 configuration file.
|
|
8
|
+
*
|
|
9
|
+
* @remarks
|
|
10
|
+
* Content is validated against a Zod schema derived from the provided shape.
|
|
11
|
+
* The configuration directory is created automatically on {@link write} if it does not exist.
|
|
12
|
+
*
|
|
13
|
+
* @typeParam T - The shape of the configuration content.
|
|
14
|
+
*/
|
|
6
15
|
export class ConfigJson {
|
|
7
16
|
path;
|
|
8
17
|
shape;
|
|
18
|
+
/** Absolute path to the directory containing the configuration file. */
|
|
9
19
|
configDir;
|
|
10
20
|
_schema = null;
|
|
11
21
|
_content = null;
|
|
22
|
+
/**
|
|
23
|
+
* Creates a new configuration wrapper.
|
|
24
|
+
*
|
|
25
|
+
* @param path - Absolute path to the JSON5 configuration file.
|
|
26
|
+
* @param shape - Zod raw shape used to build the validation schema.
|
|
27
|
+
*/
|
|
12
28
|
constructor(path, shape) {
|
|
13
29
|
this.path = path;
|
|
14
30
|
this.shape = shape;
|
|
15
31
|
this.configDir = dirname(path);
|
|
16
32
|
}
|
|
33
|
+
/**
|
|
34
|
+
* Returns the validated configuration content.
|
|
35
|
+
*
|
|
36
|
+
* @throws Error if the content has not been loaded or set.
|
|
37
|
+
*/
|
|
17
38
|
get content() {
|
|
18
39
|
if (!this._content)
|
|
19
40
|
throw new Error("Content not available");
|
|
20
41
|
return this._content;
|
|
21
42
|
}
|
|
43
|
+
/**
|
|
44
|
+
* Sets the configuration content after synchronous validation.
|
|
45
|
+
*
|
|
46
|
+
* @param data - The configuration data to set.
|
|
47
|
+
*/
|
|
22
48
|
set content(data) {
|
|
23
49
|
this._content = this.validateSync(data);
|
|
24
50
|
}
|
|
51
|
+
/**
|
|
52
|
+
* Reads and validates the configuration file from disk.
|
|
53
|
+
*
|
|
54
|
+
* @remarks
|
|
55
|
+
* The file is parsed as JSON5 and validated against the schema.
|
|
56
|
+
*/
|
|
25
57
|
async read() {
|
|
26
58
|
this._content = await this.validate(pkg.parse(await readFile(this.path, "utf8")));
|
|
27
59
|
}
|
|
60
|
+
/**
|
|
61
|
+
* Validates the current content and writes it to disk as formatted JSON.
|
|
62
|
+
*
|
|
63
|
+
* @remarks
|
|
64
|
+
* Creates the configuration directory recursively if it does not exist.
|
|
65
|
+
*/
|
|
28
66
|
async write() {
|
|
29
67
|
const [, content] = await Promise.all([
|
|
30
68
|
mkdir(this.configDir, { recursive: true }),
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ConfigJson.js","sourceRoot":"","sources":["../../src/config/ConfigJson.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,GAAG,MAAM,OAAO,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;
|
|
1
|
+
{"version":3,"file":"ConfigJson.js","sourceRoot":"","sources":["../../src/config/ConfigJson.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,GAAG,MAAM,OAAO,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAKvD;;;;;;;;GAQG;AACH,MAAM,OAAO,UAAU;IAaH;IACA;IAblB,wEAAwE;IACxD,SAAS,CAAS;IACxB,OAAO,GAAuB,IAAI,CAAC;IACnC,QAAQ,GAAa,IAAI,CAAC;IAEpC;;;;;OAKG;IACH,YACkB,IAAY,EACZ,KAAoB;QADpB,SAAI,GAAJ,IAAI,CAAQ;QACZ,UAAK,GAAL,KAAK,CAAe;QAEpC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED;;;;OAIG;IACH,IAAW,OAAO;QAChB,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;QAC7D,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,IAAW,OAAO,CAAC,IAAO;QACxB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,IAAI;QACf,IAAI,CAAC,QAAQ,GAAG,MAAM,IAAI,CAAC,QAAQ,CACjC,GAAG,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAC7C,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,KAAK;QAChB,MAAM,CAAC,EAAE,OAAO,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YACpC,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;YAC1C,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC;SAC5B,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,OAAO,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC9E,CAAC;IAES,MAAM;QACd,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvD,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAES,KAAK,CAAC,QAAQ,CAAC,OAAmB;QAC1C,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC,UAAU,CAAC,OAAO,CAAiB,CAAC;IAC3D,CAAC;IAES,YAAY,CAAC,OAAmB;QACxC,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,OAAO,CAAiB,CAAC;IACtD,CAAC;CACF"}
|
|
@@ -1,26 +1,94 @@
|
|
|
1
1
|
import { z } from "zod";
|
|
2
|
+
/** Base type for a history data item stored as a JSON object. */
|
|
2
3
|
export type HistoryItem = Record<string, unknown>;
|
|
4
|
+
/**
|
|
5
|
+
* A history entry wrapping a data item with timestamp metadata.
|
|
6
|
+
*
|
|
7
|
+
* @typeParam T - The shape of the history data item.
|
|
8
|
+
*/
|
|
3
9
|
export interface HistoryRawItem<T extends HistoryItem> {
|
|
10
|
+
/** ISO 8601 formatted timestamp string. */
|
|
4
11
|
timestamp: string;
|
|
12
|
+
/** Numeric timestamp in milliseconds since the Unix epoch. */
|
|
5
13
|
timestampRaw: number;
|
|
14
|
+
/** The history data payload. */
|
|
6
15
|
data: T;
|
|
7
16
|
}
|
|
17
|
+
/**
|
|
18
|
+
* Manages a timestamped history log persisted as a JSON5 file.
|
|
19
|
+
*
|
|
20
|
+
* @remarks
|
|
21
|
+
* Entries are validated against a Zod schema derived from the provided item shape.
|
|
22
|
+
* Items are stored in reverse-chronological order (newest first).
|
|
23
|
+
* The history directory is created automatically on {@link write} if it does not exist.
|
|
24
|
+
*
|
|
25
|
+
* @typeParam T - The shape of each history data item.
|
|
26
|
+
*/
|
|
8
27
|
export declare class HistoryJson<T extends HistoryItem> {
|
|
9
28
|
readonly path: string;
|
|
10
29
|
readonly itemShape: z.ZodRawShape;
|
|
30
|
+
/** Absolute path to the directory containing the history file. */
|
|
11
31
|
readonly historyDir: string;
|
|
12
32
|
protected _raws: HistoryRawItem<T>[];
|
|
13
33
|
protected _itemSchema: z.ZodObject | null;
|
|
14
34
|
protected _rawItemSchema: z.ZodObject | null;
|
|
15
35
|
protected _fileSchema: z.ZodArray | null;
|
|
36
|
+
/**
|
|
37
|
+
* Creates a new history log wrapper.
|
|
38
|
+
*
|
|
39
|
+
* @param path - Absolute path to the JSON5 history file.
|
|
40
|
+
* @param itemShape - Zod raw shape used to build the item validation schema.
|
|
41
|
+
*/
|
|
16
42
|
constructor(path: string, itemShape: z.ZodRawShape);
|
|
43
|
+
/**
|
|
44
|
+
* Returns all history entries as plain data items (without timestamp metadata).
|
|
45
|
+
*
|
|
46
|
+
* @returns An array of data items in reverse-chronological order.
|
|
47
|
+
*/
|
|
17
48
|
get items(): T[];
|
|
49
|
+
/**
|
|
50
|
+
* Returns a shallow copy of all raw history entries including timestamp metadata.
|
|
51
|
+
*
|
|
52
|
+
* @returns An array of raw history items in reverse-chronological order.
|
|
53
|
+
*/
|
|
18
54
|
get raws(): HistoryRawItem<T>[];
|
|
55
|
+
/**
|
|
56
|
+
* Wraps a data item with a current timestamp and prepends it to the history.
|
|
57
|
+
*
|
|
58
|
+
* @param item - The data item to add.
|
|
59
|
+
*/
|
|
19
60
|
addItem(item: T): void;
|
|
61
|
+
/**
|
|
62
|
+
* Wraps multiple data items with a current timestamp and prepends them to the history.
|
|
63
|
+
*
|
|
64
|
+
* @param items - The data items to add.
|
|
65
|
+
*/
|
|
20
66
|
addItems(items: T[]): void;
|
|
67
|
+
/**
|
|
68
|
+
* Prepends a raw history entry and re-sorts entries by timestamp.
|
|
69
|
+
*
|
|
70
|
+
* @param raw - The raw history entry to add.
|
|
71
|
+
*/
|
|
21
72
|
addRaw(raw: HistoryRawItem<T>): void;
|
|
73
|
+
/**
|
|
74
|
+
* Prepends multiple raw history entries and re-sorts entries by timestamp.
|
|
75
|
+
*
|
|
76
|
+
* @param raws - The raw history entries to add.
|
|
77
|
+
*/
|
|
22
78
|
addRaws(raws: HistoryRawItem<T>[]): void;
|
|
79
|
+
/**
|
|
80
|
+
* Reads the history file from disk, validates its content, and sorts entries.
|
|
81
|
+
*
|
|
82
|
+
* @remarks
|
|
83
|
+
* The file is parsed as JSON5 and each entry is validated against the schema.
|
|
84
|
+
*/
|
|
23
85
|
read(): Promise<void>;
|
|
86
|
+
/**
|
|
87
|
+
* Validates all entries and writes the history to disk as formatted JSON.
|
|
88
|
+
*
|
|
89
|
+
* @remarks
|
|
90
|
+
* Creates the history directory recursively if it does not exist.
|
|
91
|
+
*/
|
|
24
92
|
write(): Promise<void>;
|
|
25
93
|
protected itemSchema(): z.ZodObject<z.core.$ZodLooseShape, z.core.$strip>;
|
|
26
94
|
protected rawItemSchema(): z.ZodObject<z.core.$ZodLooseShape, z.core.$strip>;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"HistoryJson.d.ts","sourceRoot":"","sources":["../../src/history/HistoryJson.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAElD,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,WAAW;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,CAAC,CAAC;CACT;AAED,qBAAa,WAAW,CAAC,CAAC,SAAS,WAAW;
|
|
1
|
+
{"version":3,"file":"HistoryJson.d.ts","sourceRoot":"","sources":["../../src/history/HistoryJson.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,iEAAiE;AACjE,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,WAAW;IACnD,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,IAAI,EAAE,CAAC,CAAC;CACT;AAED;;;;;;;;;GASG;AACH,qBAAa,WAAW,CAAC,CAAC,SAAS,WAAW;aAe1B,IAAI,EAAE,MAAM;aACZ,SAAS,EAAE,CAAC,CAAC,WAAW;IAf1C,kEAAkE;IAClE,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAS,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,CAAM;IAC1C,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC,SAAS,GAAG,IAAI,CAAQ;IACjD,SAAS,CAAC,cAAc,EAAE,CAAC,CAAC,SAAS,GAAG,IAAI,CAAQ;IACpD,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC,QAAQ,GAAG,IAAI,CAAQ;IAEhD;;;;;OAKG;gBAEe,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,CAAC,CAAC,WAAW;IAK1C;;;;OAIG;IACH,IAAW,KAAK,IAAI,CAAC,EAAE,CAEtB;IAED;;;;OAIG;IACH,IAAW,IAAI,IAAI,cAAc,CAAC,CAAC,CAAC,EAAE,CAErC;IAED;;;;OAIG;IACI,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAI7B;;;;OAIG;IACI,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI;IAIjC;;;;OAIG;IACI,MAAM,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;IAK3C;;;;OAIG;IACI,OAAO,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI;IAK/C;;;;;OAKG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAMlC;;;;;OAKG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAUnC,SAAS,CAAC,UAAU;IAKpB,SAAS,CAAC,aAAa;IAUvB,SAAS,CAAC,UAAU;cAKJ,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;cAI1C,eAAe,CAC7B,GAAG,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,GAC9B,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;cAIb,YAAY,CAC1B,IAAI,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,GACjC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;IAI/B,SAAS,CAAC,IAAI,IAAI,IAAI;IAItB,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,CAAC;IAI3C,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE;IAIjD,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC;IAI3C,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,cAAc,CAAC,CAAC,CAAC,EAAE;CAQlD"}
|
|
@@ -3,44 +3,103 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
|
|
|
3
3
|
import { z } from "zod";
|
|
4
4
|
import pkg from "json5";
|
|
5
5
|
import { formatJson } from "@mxpicture/build-api/code";
|
|
6
|
+
/**
|
|
7
|
+
* Manages a timestamped history log persisted as a JSON5 file.
|
|
8
|
+
*
|
|
9
|
+
* @remarks
|
|
10
|
+
* Entries are validated against a Zod schema derived from the provided item shape.
|
|
11
|
+
* Items are stored in reverse-chronological order (newest first).
|
|
12
|
+
* The history directory is created automatically on {@link write} if it does not exist.
|
|
13
|
+
*
|
|
14
|
+
* @typeParam T - The shape of each history data item.
|
|
15
|
+
*/
|
|
6
16
|
export class HistoryJson {
|
|
7
17
|
path;
|
|
8
18
|
itemShape;
|
|
19
|
+
/** Absolute path to the directory containing the history file. */
|
|
9
20
|
historyDir;
|
|
10
21
|
_raws = [];
|
|
11
22
|
_itemSchema = null;
|
|
12
23
|
_rawItemSchema = null;
|
|
13
24
|
_fileSchema = null;
|
|
25
|
+
/**
|
|
26
|
+
* Creates a new history log wrapper.
|
|
27
|
+
*
|
|
28
|
+
* @param path - Absolute path to the JSON5 history file.
|
|
29
|
+
* @param itemShape - Zod raw shape used to build the item validation schema.
|
|
30
|
+
*/
|
|
14
31
|
constructor(path, itemShape) {
|
|
15
32
|
this.path = path;
|
|
16
33
|
this.itemShape = itemShape;
|
|
17
34
|
this.historyDir = dirname(path);
|
|
18
35
|
}
|
|
36
|
+
/**
|
|
37
|
+
* Returns all history entries as plain data items (without timestamp metadata).
|
|
38
|
+
*
|
|
39
|
+
* @returns An array of data items in reverse-chronological order.
|
|
40
|
+
*/
|
|
19
41
|
get items() {
|
|
20
42
|
return this._raws.map((raw) => this.toItem(raw));
|
|
21
43
|
}
|
|
44
|
+
/**
|
|
45
|
+
* Returns a shallow copy of all raw history entries including timestamp metadata.
|
|
46
|
+
*
|
|
47
|
+
* @returns An array of raw history items in reverse-chronological order.
|
|
48
|
+
*/
|
|
22
49
|
get raws() {
|
|
23
50
|
return [...this._raws];
|
|
24
51
|
}
|
|
52
|
+
/**
|
|
53
|
+
* Wraps a data item with a current timestamp and prepends it to the history.
|
|
54
|
+
*
|
|
55
|
+
* @param item - The data item to add.
|
|
56
|
+
*/
|
|
25
57
|
addItem(item) {
|
|
26
58
|
this.addRaw(this.toRaw(item));
|
|
27
59
|
}
|
|
60
|
+
/**
|
|
61
|
+
* Wraps multiple data items with a current timestamp and prepends them to the history.
|
|
62
|
+
*
|
|
63
|
+
* @param items - The data items to add.
|
|
64
|
+
*/
|
|
28
65
|
addItems(items) {
|
|
29
66
|
this.addRaws(this.toRaws(items));
|
|
30
67
|
}
|
|
68
|
+
/**
|
|
69
|
+
* Prepends a raw history entry and re-sorts entries by timestamp.
|
|
70
|
+
*
|
|
71
|
+
* @param raw - The raw history entry to add.
|
|
72
|
+
*/
|
|
31
73
|
addRaw(raw) {
|
|
32
74
|
this._raws.unshift(raw);
|
|
33
75
|
this.sort();
|
|
34
76
|
}
|
|
77
|
+
/**
|
|
78
|
+
* Prepends multiple raw history entries and re-sorts entries by timestamp.
|
|
79
|
+
*
|
|
80
|
+
* @param raws - The raw history entries to add.
|
|
81
|
+
*/
|
|
35
82
|
addRaws(raws) {
|
|
36
83
|
this._raws.unshift(...raws);
|
|
37
84
|
this.sort();
|
|
38
85
|
}
|
|
86
|
+
/**
|
|
87
|
+
* Reads the history file from disk, validates its content, and sorts entries.
|
|
88
|
+
*
|
|
89
|
+
* @remarks
|
|
90
|
+
* The file is parsed as JSON5 and each entry is validated against the schema.
|
|
91
|
+
*/
|
|
39
92
|
async read() {
|
|
40
93
|
const items = pkg.parse(await readFile(this.path, "utf8"));
|
|
41
94
|
this._raws = await this.validateFile(items);
|
|
42
95
|
this.sort();
|
|
43
96
|
}
|
|
97
|
+
/**
|
|
98
|
+
* Validates all entries and writes the history to disk as formatted JSON.
|
|
99
|
+
*
|
|
100
|
+
* @remarks
|
|
101
|
+
* Creates the history directory recursively if it does not exist.
|
|
102
|
+
*/
|
|
44
103
|
async write() {
|
|
45
104
|
const [, raws] = await Promise.all([
|
|
46
105
|
mkdir(this.historyDir, { recursive: true }),
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"HistoryJson.js","sourceRoot":"","sources":["../../src/history/HistoryJson.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,GAAG,MAAM,OAAO,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;
|
|
1
|
+
{"version":3,"file":"HistoryJson.js","sourceRoot":"","sources":["../../src/history/HistoryJson.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mxpicture/gcp-functions-fs",
|
|
3
|
-
"version": "1.1.
|
|
3
|
+
"version": "1.1.5",
|
|
4
4
|
"description": "Tools for google cloud functions",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"author": "MXPicture",
|
|
@@ -22,13 +22,15 @@
|
|
|
22
22
|
},
|
|
23
23
|
"scripts": {
|
|
24
24
|
"lint": "eslint \"src/**/*.{ts,tsx}\" --ext .ts,.tsx",
|
|
25
|
-
"build": "tsc -b ."
|
|
25
|
+
"build": "tsc -b .",
|
|
26
|
+
"docs": "typedoc",
|
|
27
|
+
"docs:clean": "rm -rf docs"
|
|
26
28
|
},
|
|
27
29
|
"publishConfig": {
|
|
28
30
|
"access": "public"
|
|
29
31
|
},
|
|
30
32
|
"dependencies": {
|
|
31
|
-
"@mxpicture/build-api": "^0.2.
|
|
33
|
+
"@mxpicture/build-api": "^0.2.57",
|
|
32
34
|
"json5": "^2.2.3",
|
|
33
35
|
"zod": "^4.3.6"
|
|
34
36
|
},
|