@theholocron/datapad 5.0.0-alpha.347 → 5.0.0-alpha.349
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 +38 -0
- package/dist/index.d.mts +91 -1
- package/dist/index.mjs +79 -3
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -87,6 +87,44 @@ the file isn't there, and throws for any other failure) and returns the first
|
|
|
87
87
|
hit as `{ path, extension, content }`, or `undefined`. Hand the result to
|
|
88
88
|
`loadConfigFromContent`.
|
|
89
89
|
|
|
90
|
+
### `loadConfigDir<T>({ cwd, dir, areas, extensions? })`
|
|
91
|
+
|
|
92
|
+
Loads the area files of a config directory (`.holocron/notifications.ts`,
|
|
93
|
+
`.holocron/repo.json`, ...) the way `loadConfigFile` loads a config. For each
|
|
94
|
+
name in the closed list `areas`, the first of `<cwd>/<dir>/<area>.{ts,js,mjs,cjs,json}`
|
|
95
|
+
that exists is loaded (`.ts` wins over `.json` when both are there). Returns
|
|
96
|
+
`{ area, path, extension, filepath, value }[]`, one entry per area that has a
|
|
97
|
+
file; a missing directory returns `[]`. A file that cannot be loaded throws
|
|
98
|
+
`ConfigFileError`. Files not named in `areas` are never read. The directory name
|
|
99
|
+
and the area names are parameters: datapad does not know what an area means, and
|
|
100
|
+
an area file may `import` a sibling in the directory.
|
|
101
|
+
|
|
102
|
+
### `readConfigDirSource({ dir, areas, fetch, extensions? })`
|
|
103
|
+
|
|
104
|
+
`loadConfigDir`'s probe for a directory that lives somewhere other than the local
|
|
105
|
+
disk. Asks `fetch("<dir>/<area>.<ext>")` in extension-priority order for each
|
|
106
|
+
area and returns `{ area, path, extension, content }[]` for the areas found.
|
|
107
|
+
It reads only the named areas; a caller that lists the whole directory and
|
|
108
|
+
fetches every file passes that tree to `writeConfigDir` instead.
|
|
109
|
+
|
|
110
|
+
### `writeConfigDir({ dir, files })`
|
|
111
|
+
|
|
112
|
+
The sandbox writer: writes a tree of fetched files (`{ path, content }`, `path`
|
|
113
|
+
relative to `dir`, e.g. `.holocron/notifications.ts` or `.holocron/lib/x.ts`)
|
|
114
|
+
into the sandbox beside the config, creating sub-directories and keeping the
|
|
115
|
+
relative paths, so `loadConfigDir({ cwd: dir, ... })` finds them and an area that
|
|
116
|
+
imports a sibling resolves it. Returns the absolute paths written. A path that is
|
|
117
|
+
absolute or leaves `dir` throws `ConfigFileError` before anything is written.
|
|
118
|
+
|
|
119
|
+
```ts
|
|
120
|
+
await withConfigSandbox({ nodeModules }, async (dir) => {
|
|
121
|
+
const { extension, content } = (await readConfigSource({ name: "holocron", fetch }))!;
|
|
122
|
+
await loadConfigFromContent({ dir, name: "holocron", extension, content });
|
|
123
|
+
await writeConfigDir({ dir, files: [{ path: ".holocron/notifications.ts", content: "export default {}" }] });
|
|
124
|
+
const areas = await loadConfigDir({ cwd: dir, dir: ".holocron", areas: ["notifications", "repo"] });
|
|
125
|
+
});
|
|
126
|
+
```
|
|
127
|
+
|
|
90
128
|
### `withConfigSandbox({ nodeModules, root?, prefix? }, run)`
|
|
91
129
|
|
|
92
130
|
Runs `run(dir)` with a throwaway directory ready to be
|
package/dist/index.d.mts
CHANGED
|
@@ -29,6 +29,38 @@ export declare class ConfigFileError extends Error {
|
|
|
29
29
|
/** Absolute path of the offending file, when known. */
|
|
30
30
|
filepath?: string | undefined);
|
|
31
31
|
}
|
|
32
|
+
/** One area file loaded from a config directory. */
|
|
33
|
+
interface ConfigDirArea<T = unknown> {
|
|
34
|
+
/** The area's name, as passed in `areas`. */
|
|
35
|
+
area: string;
|
|
36
|
+
/** The file path relative to `cwd`, with `/` separators: `.holocron/notifications.ts`. */
|
|
37
|
+
path: string;
|
|
38
|
+
/** Which extension matched. */
|
|
39
|
+
extension: string;
|
|
40
|
+
/** Absolute path of the file. */
|
|
41
|
+
filepath: string;
|
|
42
|
+
/** The file's default export (`.ts`, `.js`, `.mjs`, `.cjs`) or its parsed content (`.json`). */
|
|
43
|
+
value: T;
|
|
44
|
+
}
|
|
45
|
+
/** Options for loading the area files of a config directory from disk. */
|
|
46
|
+
interface LoadConfigDirOptions {
|
|
47
|
+
/** The directory holding `dir` — normally the one the config file was found in. */
|
|
48
|
+
cwd: string;
|
|
49
|
+
/** The directory the areas live in, relative to `cwd`: `".holocron"`. */
|
|
50
|
+
dir: string;
|
|
51
|
+
/** The closed list of area names to look for. Files not named here are never read. */
|
|
52
|
+
areas: readonly string[];
|
|
53
|
+
/** Override the extension probe order. */
|
|
54
|
+
extensions?: readonly string[];
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Load the area files of a config directory: for each name in `options.areas`, the first of
|
|
58
|
+
* `<cwd>/<dir>/<area>.{ts,js,mjs,cjs,json}` that exists, loaded the way {@link loadConfigFile} loads a config. Areas
|
|
59
|
+
* with no file are left out, so a missing directory returns `[]`. When one area has files in two formats, the
|
|
60
|
+
* extension priority picks one (`.ts` over `.json`). Throws {@link ConfigFileError} when a file exists but cannot be
|
|
61
|
+
* loaded. Holocron-agnostic: the directory and the area names are parameters, and what an area means is the caller's.
|
|
62
|
+
*/
|
|
63
|
+
export declare function loadConfigDir<T = unknown>(options: LoadConfigDirOptions): Promise<ConfigDirArea<T>[]>;
|
|
32
64
|
/** Options for finding and loading a config file from disk. */
|
|
33
65
|
interface LoadConfigFileOptions {
|
|
34
66
|
/** Directory to start looking in. */
|
|
@@ -144,6 +176,42 @@ export declare function loadLayered<T>(opts: LoadLayeredOptions<T>): Promise<Lay
|
|
|
144
176
|
* thing everywhere.
|
|
145
177
|
*/
|
|
146
178
|
export declare function mergeLayers<T>(layers: readonly (T | undefined)[]): T | undefined;
|
|
179
|
+
/** One area file's content fetched from somewhere other than the local disk. */
|
|
180
|
+
interface ConfigDirSource {
|
|
181
|
+
/** The area's name, as passed in `areas` — `"notifications"` for `.holocron/notifications.ts`. */
|
|
182
|
+
area: string;
|
|
183
|
+
/** The file path probed, relative as `fetch` was asked for it, e.g. `.holocron/notifications.ts`. */
|
|
184
|
+
path: string;
|
|
185
|
+
/** Which extension matched. */
|
|
186
|
+
extension: string;
|
|
187
|
+
/** The raw file content. */
|
|
188
|
+
content: string;
|
|
189
|
+
}
|
|
190
|
+
/** Options for fetching the area files of a config directory from a remote source. */
|
|
191
|
+
interface ReadConfigDirSourceOptions {
|
|
192
|
+
/** The directory the areas live in, relative to the config: `".holocron"`. */
|
|
193
|
+
dir: string;
|
|
194
|
+
/** The closed list of area names to look for: `["notifications", "repo"]` probes `<dir>/notifications.*` and `<dir>/repo.*`. */
|
|
195
|
+
areas: readonly string[];
|
|
196
|
+
/**
|
|
197
|
+
* Fetches one file by relative path (`.holocron/notifications.ts`): its content, or `undefined` when it doesn't
|
|
198
|
+
* exist. Throw for anything else (a network failure, a permission error) — that propagates rather than reading
|
|
199
|
+
* as "absent".
|
|
200
|
+
*/
|
|
201
|
+
fetch: (path: string) => Promise<string | undefined>;
|
|
202
|
+
/** Override the extension probe order. */
|
|
203
|
+
extensions?: readonly string[];
|
|
204
|
+
}
|
|
205
|
+
/**
|
|
206
|
+
* {@link readConfigSource} for the area files of a config directory (`.holocron/<area>.<ext>`) that live somewhere
|
|
207
|
+
* other than the local disk: for each name in `options.areas`, probes the extensions in priority order through
|
|
208
|
+
* `options.fetch` and keeps the first file that exists. Areas with no file are left out, so a repo with no
|
|
209
|
+
* directory returns `[]`. Write the result with {@link writeConfigDir} and read it back with {@link loadConfigDir}.
|
|
210
|
+
*
|
|
211
|
+
* This reads only the named areas. A caller that lists the whole directory (and so also gets the files an area
|
|
212
|
+
* imports) passes that tree to {@link writeConfigDir} directly.
|
|
213
|
+
*/
|
|
214
|
+
export declare function readConfigDirSource(options: ReadConfigDirSourceOptions): Promise<ConfigDirSource[]>;
|
|
147
215
|
/** A config file's content fetched from somewhere other than the local disk. */
|
|
148
216
|
interface ConfigSource {
|
|
149
217
|
/** The file name probed, e.g. `holocron.config.ts` — relative, as `fetch` was asked for it. */
|
|
@@ -210,4 +278,26 @@ interface ConfigSandboxOptions {
|
|
|
210
278
|
* read-only under `/var/task`) can't create a directory there.
|
|
211
279
|
*/
|
|
212
280
|
export declare function withConfigSandbox<R>(options: ConfigSandboxOptions, run: (dir: string) => Promise<R>): Promise<R>;
|
|
213
|
-
|
|
281
|
+
/** One file of a config directory's tree, as fetched from a remote source. */
|
|
282
|
+
interface ConfigDirFile {
|
|
283
|
+
/** Path relative to the sandbox directory, e.g. `.holocron/notifications.ts` or `.holocron/lib/channels.ts`. */
|
|
284
|
+
path: string;
|
|
285
|
+
/** The raw file content. */
|
|
286
|
+
content: string;
|
|
287
|
+
}
|
|
288
|
+
/** Options for writing a fetched config directory beside a config. */
|
|
289
|
+
interface WriteConfigDirOptions {
|
|
290
|
+
/** The sandbox directory (the `dir` given to {@link loadConfigFromContent}); `files` are written under it. */
|
|
291
|
+
dir: string;
|
|
292
|
+
/** The files to write; their relative paths (and so the sub-directories) are kept. */
|
|
293
|
+
files: readonly ConfigDirFile[];
|
|
294
|
+
}
|
|
295
|
+
/**
|
|
296
|
+
* Write the files fetched from a config directory (`.holocron/…`) into the sandbox beside the config, keeping each
|
|
297
|
+
* relative path, so {@link loadConfigDir} finds them and an area file that imports a sibling resolves it. Creates the
|
|
298
|
+
* sub-directories as needed and returns the absolute paths written. Throws {@link ConfigFileError} for a path that is
|
|
299
|
+
* absolute or leaves `dir`, because the paths come from a remote tree and must never write outside the sandbox; it
|
|
300
|
+
* checks every path before it writes any.
|
|
301
|
+
*/
|
|
302
|
+
export declare function writeConfigDir(options: WriteConfigDirOptions): Promise<string[]>;
|
|
303
|
+
export { type ConfigDirArea, type ConfigDirFile, type ConfigDirSource, type ConfigSandboxOptions, type ConfigSource, type LayeredResult, type LoadConfigDirOptions, type LoadConfigFileOptions, type LoadConfigFromContentOptions, type LoadLayeredOptions, type Loaded, type ReadConfigDirSourceOptions, type ReadConfigSourceOptions, type WriteConfigDirOptions, mergeConfig };
|
package/dist/index.mjs
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { join } from "node:path";
|
|
1
|
+
import { dirname, isAbsolute, join, relative, resolve } from "node:path";
|
|
3
2
|
import { mkdir, mkdtemp, readFile, rm, stat, symlink, writeFile } from "node:fs/promises";
|
|
4
3
|
import { pathToFileURL } from "node:url";
|
|
5
4
|
import { errorMessage } from "@theholocron/misc-utils";
|
|
5
|
+
import { findUpward, hasGitEntry } from "@theholocron/fs-utils";
|
|
6
6
|
import { deepMerge, deepMerge as mergeConfig } from "@theholocron/object-utils";
|
|
7
7
|
import { tmpdir } from "node:os";
|
|
8
8
|
// src/default-extensions/default-extensions.ts
|
|
@@ -111,6 +111,31 @@ function extractDefault(filepath, mod) {
|
|
|
111
111
|
if (raw === void 0 || raw === null) throw new ConfigFileError(`${filepath} must have a default export (use \`export default defineConfig({…})\`)`, filepath);
|
|
112
112
|
return raw;
|
|
113
113
|
}
|
|
114
|
+
// src/load-config-dir/load-config-dir.ts
|
|
115
|
+
/**
|
|
116
|
+
* Load the area files of a config directory: for each name in `options.areas`, the first of
|
|
117
|
+
* `<cwd>/<dir>/<area>.{ts,js,mjs,cjs,json}` that exists, loaded the way {@link loadConfigFile} loads a config. Areas
|
|
118
|
+
* with no file are left out, so a missing directory returns `[]`. When one area has files in two formats, the
|
|
119
|
+
* extension priority picks one (`.ts` over `.json`). Throws {@link ConfigFileError} when a file exists but cannot be
|
|
120
|
+
* loaded. Holocron-agnostic: the directory and the area names are parameters, and what an area means is the caller's.
|
|
121
|
+
*/
|
|
122
|
+
async function loadConfigDir(options) {
|
|
123
|
+
const areas = [];
|
|
124
|
+
for (const area of options.areas) for (const extension of options.extensions ?? DEFAULT_EXTENSIONS) {
|
|
125
|
+
const path = `${options.dir}/${area}.${extension}`;
|
|
126
|
+
const filepath = join(options.cwd, options.dir, `${area}.${extension}`);
|
|
127
|
+
if (!await isFile(filepath)) continue;
|
|
128
|
+
areas.push({
|
|
129
|
+
area,
|
|
130
|
+
path,
|
|
131
|
+
extension,
|
|
132
|
+
filepath,
|
|
133
|
+
value: await loadFile(filepath, extension)
|
|
134
|
+
});
|
|
135
|
+
break;
|
|
136
|
+
}
|
|
137
|
+
return areas;
|
|
138
|
+
}
|
|
114
139
|
// src/probe-extensions/probe-extensions.ts
|
|
115
140
|
/**
|
|
116
141
|
* Probe `dir` for `<name>.config.<ext>` in extension-priority order,
|
|
@@ -239,6 +264,32 @@ async function loadLayered(opts) {
|
|
|
239
264
|
sources
|
|
240
265
|
};
|
|
241
266
|
}
|
|
267
|
+
// src/read-config-dir-source/read-config-dir-source.ts
|
|
268
|
+
/**
|
|
269
|
+
* {@link readConfigSource} for the area files of a config directory (`.holocron/<area>.<ext>`) that live somewhere
|
|
270
|
+
* other than the local disk: for each name in `options.areas`, probes the extensions in priority order through
|
|
271
|
+
* `options.fetch` and keeps the first file that exists. Areas with no file are left out, so a repo with no
|
|
272
|
+
* directory returns `[]`. Write the result with {@link writeConfigDir} and read it back with {@link loadConfigDir}.
|
|
273
|
+
*
|
|
274
|
+
* This reads only the named areas. A caller that lists the whole directory (and so also gets the files an area
|
|
275
|
+
* imports) passes that tree to {@link writeConfigDir} directly.
|
|
276
|
+
*/
|
|
277
|
+
async function readConfigDirSource(options) {
|
|
278
|
+
const sources = [];
|
|
279
|
+
for (const area of options.areas) for (const extension of options.extensions ?? DEFAULT_EXTENSIONS) {
|
|
280
|
+
const path = `${options.dir}/${area}.${extension}`;
|
|
281
|
+
const content = await options.fetch(path);
|
|
282
|
+
if (content === void 0) continue;
|
|
283
|
+
sources.push({
|
|
284
|
+
area,
|
|
285
|
+
path,
|
|
286
|
+
extension,
|
|
287
|
+
content
|
|
288
|
+
});
|
|
289
|
+
break;
|
|
290
|
+
}
|
|
291
|
+
return sources;
|
|
292
|
+
}
|
|
242
293
|
// src/read-config-source/read-config-source.ts
|
|
243
294
|
/**
|
|
244
295
|
* {@link probeExtensions} for a config that lives somewhere other than the
|
|
@@ -294,4 +345,29 @@ async function withConfigSandbox(options, run) {
|
|
|
294
345
|
});
|
|
295
346
|
}
|
|
296
347
|
}
|
|
297
|
-
|
|
348
|
+
// src/write-config-dir/write-config-dir.ts
|
|
349
|
+
/**
|
|
350
|
+
* Write the files fetched from a config directory (`.holocron/…`) into the sandbox beside the config, keeping each
|
|
351
|
+
* relative path, so {@link loadConfigDir} finds them and an area file that imports a sibling resolves it. Creates the
|
|
352
|
+
* sub-directories as needed and returns the absolute paths written. Throws {@link ConfigFileError} for a path that is
|
|
353
|
+
* absolute or leaves `dir`, because the paths come from a remote tree and must never write outside the sandbox; it
|
|
354
|
+
* checks every path before it writes any.
|
|
355
|
+
*/
|
|
356
|
+
async function writeConfigDir(options) {
|
|
357
|
+
const root = resolve(options.dir);
|
|
358
|
+
const targets = options.files.map((file) => {
|
|
359
|
+
const target = resolve(root, file.path);
|
|
360
|
+
const rel = relative(root, target);
|
|
361
|
+
if (isAbsolute(file.path) || rel === "" || rel.startsWith("..") || isAbsolute(rel)) throw new ConfigFileError(`refusing to write ${file.path}: it is not inside ${options.dir}`, target);
|
|
362
|
+
return {
|
|
363
|
+
target,
|
|
364
|
+
content: file.content
|
|
365
|
+
};
|
|
366
|
+
});
|
|
367
|
+
for (const { target, content } of targets) {
|
|
368
|
+
await mkdir(dirname(target), { recursive: true });
|
|
369
|
+
await writeFile(target, content, "utf8");
|
|
370
|
+
}
|
|
371
|
+
return targets.map(({ target }) => target);
|
|
372
|
+
}
|
|
373
|
+
export { ConfigFileError, DEFAULT_EXTENSIONS, createDefineConfig, loadConfigDir, loadConfigFile, loadConfigFromContent, loadLayered, mergeConfig, mergeLayers, readConfigDirSource, readConfigSource, withConfigSandbox, writeConfigDir };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@theholocron/datapad",
|
|
3
|
-
"version": "5.0.0-alpha.
|
|
3
|
+
"version": "5.0.0-alpha.349",
|
|
4
4
|
"description": "Generic config-file loading for Holocron — discover, load (JSON/JS/TS/ESM/CJS), and merge <name>.config.* files with a typed defineConfig.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"config",
|
|
@@ -47,9 +47,9 @@
|
|
|
47
47
|
"tsdown": "^0.23.4",
|
|
48
48
|
"typescript": "^5.9.3",
|
|
49
49
|
"vitest": "^5.0.5",
|
|
50
|
-
"@theholocron/tsconfig": "^8.9.0-alpha.8",
|
|
51
50
|
"@theholocron/eslint-config": "^8.9.0-alpha.8",
|
|
52
51
|
"@theholocron/vitest-config": "^8.9.0-alpha.8",
|
|
52
|
+
"@theholocron/tsconfig": "^8.9.0-alpha.8",
|
|
53
53
|
"@theholocron/tsdown-config": "^8.9.0-alpha.8"
|
|
54
54
|
},
|
|
55
55
|
"engines": {
|