@venizia/ignis-helpers 0.4.4 → 0.4.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.
@@ -25,11 +25,36 @@ export declare class ModuleUtility {
25
25
  static register(opts: {
26
26
  modules: Record<string, AnyType>;
27
27
  }): void;
28
- /** Loads the module. Use this everywhere except a constructor, which cannot await. */
28
+ /**
29
+ * The file `module` resolves to from the project root under the ES module conditions (`import`), so
30
+ * the peer is the very instance an application's own `import` of it gets. `undefined` when it does not
31
+ * resolve there or the runtime has no resolver: the caller falls back to a plain `import()`.
32
+ */
33
+ private static resolveEsmFile;
34
+ /**
35
+ * Loads the module as an ES module, resolved from the project root: a peer that ships both builds
36
+ * (`bullmq`, `socket.io-client`) is loaded as the copy the application's own `import` gets, not a second
37
+ * one. A module handed over with {@link register} wins; one that does not resolve from the project root is
38
+ * imported by name as before. Use this everywhere except a constructor, which cannot await - see {@link preload}.
39
+ */
29
40
  static load<T = AnyType>(opts: {
30
41
  module: string;
31
42
  }): Promise<T>;
32
- /** Sync twin of {@link load}, for a constructor or any path that cannot await. */
43
+ /**
44
+ * The explicit register path for what a constructor needs: loads each module with {@link load} and
45
+ * registers it, so the synchronous {@link loadSync} returns that ES module copy afterwards. Call it once
46
+ * at the entrypoint, before the helpers are constructed. A module already registered is kept; every module
47
+ * is loaded before any is registered, so one that is missing registers nothing.
48
+ */
49
+ static preload(opts: {
50
+ modules: Array<string>;
51
+ }): Promise<void>;
52
+ /**
53
+ * Sync twin of {@link load}, for a constructor or any path that cannot await. It resolves with
54
+ * `require`, so a peer that ships both builds comes back as its CommonJS copy - a second instance next to
55
+ * the one an application's `import` holds, and `instanceof` across the two fails. `await preload(...)` at the
56
+ * entrypoint registers the ES module copy first, and this returns that.
57
+ */
33
58
  static loadSync<T = AnyType>(opts: {
34
59
  module: string;
35
60
  }): T;
@@ -1 +1 @@
1
- {"version":3,"file":"module.utility.d.ts","sourceRoot":"","sources":["../../../src/utilities/module.utility.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAO9C,4LAA4L;AAC5L,qBAAa,aAAa;IACxB,0RAA0R;IAC1R,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAwD;IAE1F,OAAO,CAAC,MAAM,CAAC,cAAc;IAa7B,0PAA0P;IAC1P,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAI1D,MAAM,CAAC,cAAc,IAAI,MAAM;IAI/B,uHAAuH;IACvH,OAAO,CAAC,MAAM,CAAC,UAAU;IAIzB,OAAO,CAAC,MAAM,CAAC,IAAI;IAanB;;;;;;;;;OASG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI;IAOjE,sFAAsF;WACzE,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC;IAcpE,kFAAkF;IAClF,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,CAAC;IAczD;;;;;;;OAOG;IACH,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE;QAC3B,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QACvB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,eAAe,CAAC,EAAE,OAAO,CAAC;KAC3B,GAAG,IAAI;CAgBT"}
1
+ {"version":3,"file":"module.utility.d.ts","sourceRoot":"","sources":["../../../src/utilities/module.utility.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAO9C,4LAA4L;AAC5L,qBAAa,aAAa;IACxB,0RAA0R;IAC1R,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAwD;IAE1F,OAAO,CAAC,MAAM,CAAC,cAAc;IAa7B,0PAA0P;IAC1P,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAI1D,MAAM,CAAC,cAAc,IAAI,MAAM;IAI/B,uHAAuH;IACvH,OAAO,CAAC,MAAM,CAAC,UAAU;IAIzB,OAAO,CAAC,MAAM,CAAC,IAAI;IAanB;;;;;;;;;OASG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI;IAOjE;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAa7B;;;;;OAKG;WACU,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC;IAepE;;;;;OAKG;WACU,OAAO,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAWrE;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,CAAC;IAczD;;;;;;;OAOG;IACH,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE;QAC3B,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QACvB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,eAAe,CAAC,EAAE,OAAO,CAAC;KAC3B,GAAG,IAAI;CAgBT"}
@@ -1,5 +1,6 @@
1
1
  import { createRequire } from 'node:module';
2
2
  import path from 'node:path';
3
+ import { pathToFileURL } from 'node:url';
3
4
  import { LoggerFactory } from '../modules/logger/index.js';
4
5
  import { getError } from '../modules/error/index.js';
5
6
  import { ProjectRootRegistry } from './project-root.utility.js';
@@ -53,20 +54,62 @@ export class ModuleUtility {
53
54
  this.registered.set(module, value);
54
55
  }
55
56
  }
56
- /** Loads the module. Use this everywhere except a constructor, which cannot await. */
57
+ /**
58
+ * The file `module` resolves to from the project root under the ES module conditions (`import`), so
59
+ * the peer is the very instance an application's own `import` of it gets. `undefined` when it does not
60
+ * resolve there or the runtime has no resolver: the caller falls back to a plain `import()`.
61
+ */
62
+ static resolveEsmFile(opts) {
63
+ if (typeof Bun === 'undefined') {
64
+ return undefined;
65
+ }
66
+ try {
67
+ const file = Bun.resolveSync(opts.module, this.getProjectRoot());
68
+ return path.isAbsolute(file) ? file : undefined;
69
+ }
70
+ catch {
71
+ return undefined;
72
+ }
73
+ }
74
+ /**
75
+ * Loads the module as an ES module, resolved from the project root: a peer that ships both builds
76
+ * (`bullmq`, `socket.io-client`) is loaded as the copy the application's own `import` gets, not a second
77
+ * one. A module handed over with {@link register} wins; one that does not resolve from the project root is
78
+ * imported by name as before. Use this everywhere except a constructor, which cannot await - see {@link preload}.
79
+ */
57
80
  static async load(opts) {
58
81
  const { module } = opts;
59
82
  if (this.registered.has(module)) {
60
83
  return this.registered.get(module);
61
84
  }
62
85
  try {
63
- return (await import(module));
86
+ const file = this.resolveEsmFile({ module });
87
+ return (await import(file === undefined ? module : pathToFileURL(file).href));
64
88
  }
65
89
  catch (error) {
66
90
  throw this.fail({ method: 'load', module, error });
67
91
  }
68
92
  }
69
- /** Sync twin of {@link load}, for a constructor or any path that cannot await. */
93
+ /**
94
+ * The explicit register path for what a constructor needs: loads each module with {@link load} and
95
+ * registers it, so the synchronous {@link loadSync} returns that ES module copy afterwards. Call it once
96
+ * at the entrypoint, before the helpers are constructed. A module already registered is kept; every module
97
+ * is loaded before any is registered, so one that is missing registers nothing.
98
+ */
99
+ static async preload(opts) {
100
+ const loaded = {};
101
+ for (const module of opts.modules) {
102
+ // `load` answers from the registry first, so a module the application handed over comes back as itself.
103
+ loaded[module] = await this.load({ module });
104
+ }
105
+ this.register({ modules: loaded });
106
+ }
107
+ /**
108
+ * Sync twin of {@link load}, for a constructor or any path that cannot await. It resolves with
109
+ * `require`, so a peer that ships both builds comes back as its CommonJS copy - a second instance next to
110
+ * the one an application's `import` holds, and `instanceof` across the two fails. `await preload(...)` at the
111
+ * entrypoint registers the ES module copy first, and this returns that.
112
+ */
70
113
  static loadSync(opts) {
71
114
  const { module } = opts;
72
115
  if (this.registered.has(module)) {
@@ -1 +1 @@
1
- {"version":3,"file":"module.utility.js","sourceRoot":"","sources":["../../../src/utilities/module.utility.ts"],"names":[],"mappings":"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","sourcesContent":["import { createRequire } from 'node:module';\nimport path from 'node:path';\nimport type { AnyType } from '@/common/types';\nimport { LoggerFactory } from '@/modules/logger';\nimport { getError } from '@/modules/error';\nimport { ProjectRootRegistry } from './project-root.utility';\n\nconst logger = LoggerFactory.getLogger(['ModuleUtility']);\n\n/** Loads an optional peer without letting `Bun.build` see it: every specifier stays a parameter, so there is no literal (nor a `minify.syntax`-folded const) for the bundler to resolve. */\nexport class ModuleUtility {\n /** Peers handed over by the application, keyed by specifier. Checked before any filesystem lookup. The map lives in a globalThis slot because a process (or a compiled bundle) can carry two copies of this module, and a peer registered through one copy must be found by the other. */\n private static readonly registered: Map<string, AnyType> = ModuleUtility.sharedRegistry();\n\n private static sharedRegistry(): Map<string, AnyType> {\n const slot = Symbol.for('ignis:module-registry');\n const shared: Map<string, AnyType> | undefined = Reflect.get(globalThis, slot);\n if (shared) {\n return shared;\n }\n\n const created = new Map<string, AnyType>();\n Reflect.set(globalThis, slot, created);\n\n return created;\n }\n\n /** Called by the application once it knows its root (`configs.projectRoot` or the cwd); every peer lookup below follows it. Delegates to `ProjectRootRegistry`, which a browser Worker host reaches too through `/core` - the two must share ONE slot. */\n static setProjectRoot(opts: { projectRoot: string }): void {\n ProjectRootRegistry.set(opts);\n }\n\n static getProjectRoot(): string {\n return ProjectRootRegistry.getShared() ?? process.cwd();\n }\n\n /** Resolves peers against the APP's node_modules (under the project root), not this package's own `dist/` location. */\n private static appRequire() {\n return createRequire(path.join(this.getProjectRoot(), 'node_modules'));\n }\n\n private static fail(opts: { method: string; module: string; error: unknown; scope?: string }) {\n const { method, module, error, scope } = opts;\n const reason = error instanceof Error ? error.message : String(error);\n\n logger.for(method).error(\"Failed to load '%s' | Error: %s\", module, reason);\n\n return getError({\n message: `[ModuleUtility.${method}] ${module} is required, resolved from ${this.getProjectRoot()}${\n scope ? ` for ${scope}` : ''\n }. Please install '${module}' | Error: ${reason}`,\n });\n }\n\n /**\n * Hands the framework a peer the application already holds, so no filesystem lookup is needed.\n * A `bun build --compile` binary ships without `node_modules`, which leaves runtime resolution\n * nothing to resolve against: the application imports such a peer statically - that import is\n * what gets it into the binary - and registers it here before the consuming component boots.\n *\n * Deliberately does not log. It runs at the entrypoint of exactly the deployment that has no\n * logger provider yet, where `LoggerFactory` throws - and a throw mid-loop would drop every\n * module after the first.\n */\n static register(opts: { modules: Record<string, AnyType> }): void {\n const modulesEntries = Object.entries(opts.modules);\n for (const [module, value] of modulesEntries) {\n this.registered.set(module, value);\n }\n }\n\n /** Loads the module. Use this everywhere except a constructor, which cannot await. */\n static async load<T = AnyType>(opts: { module: string }): Promise<T> {\n const { module } = opts;\n\n if (this.registered.has(module)) {\n return this.registered.get(module) as T;\n }\n\n try {\n return (await import(module)) as T;\n } catch (error) {\n throw this.fail({ method: 'load', module, error });\n }\n }\n\n /** Sync twin of {@link load}, for a constructor or any path that cannot await. */\n static loadSync<T = AnyType>(opts: { module: string }): T {\n const { module } = opts;\n\n if (this.registered.has(module)) {\n return this.registered.get(module) as T;\n }\n\n try {\n return this.appRequire()(module) as T;\n } catch (error) {\n throw this.fail({ method: 'loadSync', module, error });\n }\n }\n\n /**\n * Presence check only - throws naming what to install, without executing the module.\n *\n * `allowRegistered` must be set only where {@link load} or {@link loadSync} is what finally loads\n * the module. Where the consumer resolves the specifier itself - `pino.transport()` inside a\n * worker thread, or any caller with its own `createRequire` - the registry cannot reach it, and\n * counting a registration as installed would replace this precise error with an opaque one.\n */\n static assertInstalled(opts: {\n modules: Array<string>;\n scope?: string;\n allowRegistered?: boolean;\n }): void {\n const { modules, scope, allowRegistered = false } = opts;\n const appRequire = this.appRequire();\n\n for (const module of modules) {\n if (allowRegistered && this.registered.has(module)) {\n continue;\n }\n\n try {\n appRequire.resolve(module);\n } catch (error) {\n throw this.fail({ method: 'assertInstalled', module, error, scope });\n }\n }\n }\n}\n"]}
1
+ {"version":3,"file":"module.utility.js","sourceRoot":"","sources":["../../../src/utilities/module.utility.ts"],"names":[],"mappings":"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","sourcesContent":["import { createRequire } from 'node:module';\nimport path from 'node:path';\nimport { pathToFileURL } from 'node:url';\nimport type { AnyType } from '@/common/types';\nimport { LoggerFactory } from '@/modules/logger';\nimport { getError } from '@/modules/error';\nimport { ProjectRootRegistry } from './project-root.utility';\n\nconst logger = LoggerFactory.getLogger(['ModuleUtility']);\n\n/** Loads an optional peer without letting `Bun.build` see it: every specifier stays a parameter, so there is no literal (nor a `minify.syntax`-folded const) for the bundler to resolve. */\nexport class ModuleUtility {\n /** Peers handed over by the application, keyed by specifier. Checked before any filesystem lookup. The map lives in a globalThis slot because a process (or a compiled bundle) can carry two copies of this module, and a peer registered through one copy must be found by the other. */\n private static readonly registered: Map<string, AnyType> = ModuleUtility.sharedRegistry();\n\n private static sharedRegistry(): Map<string, AnyType> {\n const slot = Symbol.for('ignis:module-registry');\n const shared: Map<string, AnyType> | undefined = Reflect.get(globalThis, slot);\n if (shared) {\n return shared;\n }\n\n const created = new Map<string, AnyType>();\n Reflect.set(globalThis, slot, created);\n\n return created;\n }\n\n /** Called by the application once it knows its root (`configs.projectRoot` or the cwd); every peer lookup below follows it. Delegates to `ProjectRootRegistry`, which a browser Worker host reaches too through `/core` - the two must share ONE slot. */\n static setProjectRoot(opts: { projectRoot: string }): void {\n ProjectRootRegistry.set(opts);\n }\n\n static getProjectRoot(): string {\n return ProjectRootRegistry.getShared() ?? process.cwd();\n }\n\n /** Resolves peers against the APP's node_modules (under the project root), not this package's own `dist/` location. */\n private static appRequire() {\n return createRequire(path.join(this.getProjectRoot(), 'node_modules'));\n }\n\n private static fail(opts: { method: string; module: string; error: unknown; scope?: string }) {\n const { method, module, error, scope } = opts;\n const reason = error instanceof Error ? error.message : String(error);\n\n logger.for(method).error(\"Failed to load '%s' | Error: %s\", module, reason);\n\n return getError({\n message: `[ModuleUtility.${method}] ${module} is required, resolved from ${this.getProjectRoot()}${\n scope ? ` for ${scope}` : ''\n }. Please install '${module}' | Error: ${reason}`,\n });\n }\n\n /**\n * Hands the framework a peer the application already holds, so no filesystem lookup is needed.\n * A `bun build --compile` binary ships without `node_modules`, which leaves runtime resolution\n * nothing to resolve against: the application imports such a peer statically - that import is\n * what gets it into the binary - and registers it here before the consuming component boots.\n *\n * Deliberately does not log. It runs at the entrypoint of exactly the deployment that has no\n * logger provider yet, where `LoggerFactory` throws - and a throw mid-loop would drop every\n * module after the first.\n */\n static register(opts: { modules: Record<string, AnyType> }): void {\n const modulesEntries = Object.entries(opts.modules);\n for (const [module, value] of modulesEntries) {\n this.registered.set(module, value);\n }\n }\n\n /**\n * The file `module` resolves to from the project root under the ES module conditions (`import`), so\n * the peer is the very instance an application's own `import` of it gets. `undefined` when it does not\n * resolve there or the runtime has no resolver: the caller falls back to a plain `import()`.\n */\n private static resolveEsmFile(opts: { module: string }): string | undefined {\n if (typeof Bun === 'undefined') {\n return undefined;\n }\n\n try {\n const file = Bun.resolveSync(opts.module, this.getProjectRoot());\n return path.isAbsolute(file) ? file : undefined;\n } catch {\n return undefined;\n }\n }\n\n /**\n * Loads the module as an ES module, resolved from the project root: a peer that ships both builds\n * (`bullmq`, `socket.io-client`) is loaded as the copy the application's own `import` gets, not a second\n * one. A module handed over with {@link register} wins; one that does not resolve from the project root is\n * imported by name as before. Use this everywhere except a constructor, which cannot await - see {@link preload}.\n */\n static async load<T = AnyType>(opts: { module: string }): Promise<T> {\n const { module } = opts;\n\n if (this.registered.has(module)) {\n return this.registered.get(module) as T;\n }\n\n try {\n const file = this.resolveEsmFile({ module });\n return (await import(file === undefined ? module : pathToFileURL(file).href)) as T;\n } catch (error) {\n throw this.fail({ method: 'load', module, error });\n }\n }\n\n /**\n * The explicit register path for what a constructor needs: loads each module with {@link load} and\n * registers it, so the synchronous {@link loadSync} returns that ES module copy afterwards. Call it once\n * at the entrypoint, before the helpers are constructed. A module already registered is kept; every module\n * is loaded before any is registered, so one that is missing registers nothing.\n */\n static async preload(opts: { modules: Array<string> }): Promise<void> {\n const loaded: Record<string, AnyType> = {};\n\n for (const module of opts.modules) {\n // `load` answers from the registry first, so a module the application handed over comes back as itself.\n loaded[module] = await this.load({ module });\n }\n\n this.register({ modules: loaded });\n }\n\n /**\n * Sync twin of {@link load}, for a constructor or any path that cannot await. It resolves with\n * `require`, so a peer that ships both builds comes back as its CommonJS copy - a second instance next to\n * the one an application's `import` holds, and `instanceof` across the two fails. `await preload(...)` at the\n * entrypoint registers the ES module copy first, and this returns that.\n */\n static loadSync<T = AnyType>(opts: { module: string }): T {\n const { module } = opts;\n\n if (this.registered.has(module)) {\n return this.registered.get(module) as T;\n }\n\n try {\n return this.appRequire()(module) as T;\n } catch (error) {\n throw this.fail({ method: 'loadSync', module, error });\n }\n }\n\n /**\n * Presence check only - throws naming what to install, without executing the module.\n *\n * `allowRegistered` must be set only where {@link load} or {@link loadSync} is what finally loads\n * the module. Where the consumer resolves the specifier itself - `pino.transport()` inside a\n * worker thread, or any caller with its own `createRequire` - the registry cannot reach it, and\n * counting a registration as installed would replace this precise error with an opaque one.\n */\n static assertInstalled(opts: {\n modules: Array<string>;\n scope?: string;\n allowRegistered?: boolean;\n }): void {\n const { modules, scope, allowRegistered = false } = opts;\n const appRequire = this.appRequire();\n\n for (const module of modules) {\n if (allowRegistered && this.registered.has(module)) {\n continue;\n }\n\n try {\n appRequire.resolve(module);\n } catch (error) {\n throw this.fail({ method: 'assertInstalled', module, error, scope });\n }\n }\n }\n}\n"]}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/ignis-helpers",
3
- "version": "0.4.4",
3
+ "version": "0.4.5",
4
4
  "description": "Production-ready TypeScript utility library: pluggable logging (winston or pino behind one ILogger contract), Redis single/cluster/sentinel with pub/sub, BullMQ/MQTT/Kafka message queues, MinIO/Disk/Bun-S3 object storage, AES-256/RSA/ECDH cryptography, Snowflake UID generation, cron scheduling, Socket.IO/WebSocket, TCP/TLS/UDP networking, HTTP clients, secrets/Vault, worker thread pools, and environment management. Sub-path imports isolate optional peer dependencies so the root barrel never forces a peer into your bundle.",
5
5
  "keywords": [
6
6
  "aes",
@@ -194,7 +194,7 @@
194
194
  "@socket.io/redis-emitter": "^5.1.0",
195
195
  "@types/bun": "^1.4.3",
196
196
  "@types/luxon": "^3.7.6",
197
- "@venizia/dev-configs": "0.4.4",
197
+ "@venizia/dev-configs": "0.4.5",
198
198
  "axios": "^1.20.0",
199
199
  "bullmq": "^6.4.0",
200
200
  "cron": "^4.4.0",