@theholocron/datapad 5.0.0-alpha.348 → 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 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
- export { type ConfigSandboxOptions, type ConfigSource, type LayeredResult, type LoadConfigFileOptions, type LoadConfigFromContentOptions, type LoadLayeredOptions, type Loaded, type ReadConfigSourceOptions, mergeConfig };
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 { findUpward, hasGitEntry } from "@theholocron/fs-utils";
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
- export { ConfigFileError, DEFAULT_EXTENSIONS, createDefineConfig, loadConfigFile, loadConfigFromContent, loadLayered, mergeConfig, mergeLayers, readConfigSource, withConfigSandbox };
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.348",
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",
@@ -33,9 +33,9 @@
33
33
  ],
34
34
  "dependencies": {
35
35
  "tsx": "4.23.15",
36
+ "@theholocron/fs-utils": "^1.17.0-alpha.1",
36
37
  "@theholocron/misc-utils": "^1.17.0-alpha.1",
37
- "@theholocron/object-utils": "^1.17.0-alpha.1",
38
- "@theholocron/fs-utils": "^1.17.0-alpha.1"
38
+ "@theholocron/object-utils": "^1.17.0-alpha.1"
39
39
  },
40
40
  "devDependencies": {
41
41
  "@types/node": "^26",
@@ -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": {