@ciqol/resenv 0.1.0-beta.1

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@ciqol/resenv",
+  "version": "0.1.0-beta.1",
+  "description": "Replace environment references with their resolved values at application startup",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ciqol/resenv.git"
+  },
+  "homepage": "https://github.com/ciqol/resenv#readme",
+  "bugs": {
+    "url": "https://github.com/ciqol/resenv/issues"
+  },
+  "keywords": [
+    "environment",
+    "dotenv",
+    "secrets",
+    "nx"
+  ],
+  "main": "./index.cjs",
+  "module": "./index.mjs",
+  "types": "./index.d.cts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./index.d.mts",
+        "require": "./index.d.cts",
+        "default": "./index.d.mts"
+      },
+      "import": "./index.mjs",
+      "require": "./index.cjs",
+      "default": "./index.mjs"
+    },
+    "./resolve": {
+      "types": {
+        "import": "./resolve.d.mts",
+        "require": "./resolve.d.cts",
+        "default": "./resolve.d.mts"
+      },
+      "import": "./resolve.mjs",
+      "require": "./resolve.cjs"
+    },
+    "./resolve-commands": {
+      "types": {
+        "import": "./resolve-commands.d.mts",
+        "require": "./resolve-commands.d.cts",
+        "default": "./resolve-commands.d.mts"
+      },
+      "import": "./resolve-commands.mjs",
+      "require": "./resolve-commands.cjs"
+    },
+    "./resolve-doppler": {
+      "types": {
+        "import": "./resolve-doppler.d.mts",
+        "require": "./resolve-doppler.d.cts",
+        "default": "./resolve-doppler.d.mts"
+      },
+      "import": "./resolve-doppler.mjs",
+      "require": "./resolve-doppler.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "resenv": "./bin/resenv.cjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {},
+  "files": [
+    "*.cjs",
+    "*.mjs",
+    "*.d.cts",
+    "*.d.mts",
+    "doppler",
+    "bin",
+    "types",
+    "README.md",
+    "LICENSE",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "docs"
+  ]
+}

package/preload.cjs

@@ -0,0 +1,31 @@
+'use strict';
+
+var index = require('./index.cjs');
+var errors = require('./errors.cjs');
+
+let activeMode;
+function assertNoPreload() {
+    if (activeMode) {
+        throw new errors.ResenvError('CONFLICTING_PRELOADS', 'Use the resenv CLI or a resenv preload for this process. Combining them can reinterpret fetched values.');
+    }
+}
+function resolvePreload(mode) {
+    try {
+        // A second mode could interpret data fetched by the first as executable input.
+        if (activeMode && activeMode !== mode) {
+            throw new errors.ResenvError('CONFLICTING_PRELOADS', 'Use one resenv preload per process. To combine Doppler and commands, use resenv run --commands or one library call with commands enabled.');
+        }
+        if (activeMode) {
+            return;
+        }
+        activeMode = mode;
+        index.resolve(process.env, { replace: true, commands: mode === 'commands' });
+    }
+    catch (err) {
+        process.stderr.write(`${index.formatError(err)}\n`);
+        process.exit(1);
+    }
+}
+
+exports.assertNoPreload = assertNoPreload;
+exports.resolvePreload = resolvePreload;

package/resolve-commands.cjs

@@ -0,0 +1,5 @@
+'use strict';
+
+var preload = require('./preload.cjs');
+
+preload.resolvePreload('commands');

package/resolve-commands.d.cts

@@ -0,0 +1 @@
+export * from './types/src/resolve-commands.js'

package/resolve-commands.d.mts

@@ -0,0 +1 @@
+export * from './types/src/resolve-commands.js'

package/resolve-commands.mjs

@@ -0,0 +1 @@
+import './resolve-commands.cjs';

package/resolve-doppler.cjs

@@ -0,0 +1,4 @@
+'use strict';
+
+require('./resolve.cjs');
+

package/resolve-doppler.d.cts

@@ -0,0 +1 @@
+export * from './types/src/resolve-doppler.js'

package/resolve-doppler.d.mts

@@ -0,0 +1 @@
+export * from './types/src/resolve-doppler.js'

package/resolve-doppler.mjs

@@ -0,0 +1 @@
+import './resolve-doppler.cjs';

package/resolve.cjs

@@ -0,0 +1,5 @@
+'use strict';
+
+var preload = require('./preload.cjs');
+
+preload.resolvePreload('doppler');

package/resolve.d.cts

@@ -0,0 +1 @@
+export * from './types/src/resolve.js'

package/resolve.d.mts

@@ -0,0 +1 @@
+export * from './types/src/resolve.js'

package/resolve.mjs

@@ -0,0 +1 @@
+import './resolve.cjs';

package/types/bin/resenv.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/types/src/assert-safe-diagnostics.d.ts

@@ -0,0 +1 @@
+export declare function assertSafeDiagnostics(): void;

package/types/src/commands.d.ts

@@ -0,0 +1,4 @@
+import type { DebugLogger } from 'node:util';
+import type { Environment, ResolveOptions } from './types.js';
+declare function resolveCommands(env: Readonly<Environment>, { commandTimeoutMs }: ResolveOptions, debug: DebugLogger): Environment;
+export { resolveCommands };

package/types/src/doppler/auth.d.ts

@@ -0,0 +1,19 @@
+import type { Environment } from '../types.js';
+import type { Request } from './http.js';
+import type { CredentialSystem } from './system.js';
+type LoginOptions = {
+    readonly cli?: boolean;
+    readonly noBrowser?: boolean;
+};
+type LoginDependencies = {
+    readonly request?: Request;
+    readonly system?: CredentialSystem;
+    readonly output?: (text: string) => void;
+    readonly interactive?: boolean;
+    readonly env?: Readonly<Environment>;
+    readonly sleep?: (ms: number) => Promise<unknown>;
+    readonly now?: () => number;
+};
+declare function credential(env: Readonly<Environment>, system?: Pick<CredentialSystem, 'read' | 'cliToken'>): Promise<string>;
+declare function login({ cli, noBrowser }?: LoginOptions, { request, system, output, interactive, env, sleep, now }?: LoginDependencies): Promise<'cli' | 'native'>;
+export { credential, login };

package/types/src/doppler/bridge.d.ts

@@ -0,0 +1,4 @@
+import type { Environment } from '../types.js';
+import type { SyncRunner } from './system.js';
+declare function resolveDopplerSync(env: Readonly<Environment>, run?: SyncRunner): Environment;
+export { resolveDopplerSync };

package/types/src/doppler/http.d.ts

@@ -0,0 +1,9 @@
+export type RequestOptions = {
+    readonly token?: string;
+    readonly body?: Readonly<Record<string, string>>;
+    readonly pending?: boolean;
+};
+export type Request = (path: string, options?: RequestOptions) => Promise<Record<string, unknown> | null>;
+declare function createClient(fetchImpl?: typeof globalThis.fetch): Request;
+declare function validateToken(token: unknown): string;
+export { createClient, validateToken };

package/types/src/doppler/references.d.ts

@@ -0,0 +1,9 @@
+import type { Environment } from '../types.js';
+type Reference = {
+    readonly name: string;
+    readonly project: string;
+    readonly config: string;
+    readonly key: string;
+};
+declare function references(env: Readonly<Environment>): Reference[];
+export { references };

package/types/src/doppler/resolve.d.ts

@@ -0,0 +1,9 @@
+import type { Environment } from '../types.js';
+import { credential } from './auth.js';
+import type { Request } from './http.js';
+type ResolveDependencies = {
+    readonly request?: Request;
+    readonly getCredential?: typeof credential;
+};
+declare function resolveReferences(env: Readonly<Environment>, { request, getCredential }?: ResolveDependencies): Promise<Environment>;
+export { resolveReferences };

package/types/src/doppler/system.d.ts

@@ -0,0 +1,24 @@
+import type { SpawnSyncOptionsWithStringEncoding, SpawnSyncReturns } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import type { Environment } from '../types.js';
+type SyncOptions = SpawnSyncOptionsWithStringEncoding & {
+    readonly detached?: boolean;
+};
+export type SyncRunner = (file: string, args: readonly string[], options: SyncOptions) => SpawnSyncReturns<string>;
+type SystemOptions = {
+    readonly platform?: NodeJS.Platform;
+    readonly run?: SyncRunner;
+    readonly exists?: typeof existsSync;
+};
+export type CredentialSystem = ReturnType<typeof createSystem>;
+declare function helperEnvironment(): Environment;
+declare function createSystem({ platform, run, exists }?: SystemOptions): {
+    read: () => string | undefined;
+    write: (token: string) => void;
+    remove: () => void;
+    cliToken: () => string | undefined;
+    cliLogin: () => void;
+    openBrowser: (url: string) => boolean;
+    canStore: boolean;
+};
+export { createSystem, helperEnvironment };

package/types/src/doppler-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/types/src/errors.d.ts

@@ -0,0 +1,5 @@
+declare class ResenvError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export { ResenvError };

package/types/src/index.d.ts

@@ -0,0 +1,7 @@
+import { ResenvError } from './errors.js';
+import type { Environment, ResolveOptions } from './types.js';
+export type { Environment, ResolveOptions } from './types.js';
+/** Always return a resolved copy; optionally commit replacements to the input. */
+declare function resolve(env?: Readonly<Environment>, options?: ResolveOptions): Environment;
+declare function formatError(error: unknown): string;
+export { ResenvError, resolve, formatError };

package/types/src/preload.d.ts

@@ -0,0 +1,4 @@
+type PreloadMode = 'commands' | 'doppler';
+export declare function assertNoPreload(): void;
+export declare function resolvePreload(mode: PreloadMode): void;
+export {};

package/types/src/resolve-commands.d.ts

@@ -0,0 +1 @@
+export {};

package/types/src/resolve-doppler.d.ts

@@ -0,0 +1 @@
+import './resolve.js';

package/types/src/resolve.d.ts

@@ -0,0 +1 @@
+export {};

package/types/src/types.d.ts

@@ -0,0 +1,9 @@
+export type Environment = Record<string, string | undefined>;
+export type ResolveOptions = {
+    /** Also replace values in the input environment. Default false; always return a copy. */
+    readonly replace?: boolean;
+    /** Execute whole-value $(command) expressions using /bin/sh. Default false. */
+    readonly commands?: boolean;
+    /** Per-command timeout in milliseconds. Default 30000. */
+    readonly commandTimeoutMs?: number;
+};

package/types/src/values.d.ts

@@ -0,0 +1,5 @@
+import type { Environment } from './types.js';
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function isEnvironment(value: unknown): value is Environment;
+export declare function hasErrorCode(err: unknown, code: string): boolean;
+export declare function copyEnvironment(env: Readonly<Environment>): Environment;

package/values.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isEnvironment(value) {
+    return isRecord(value) && Object.values(value).every(item => typeof item === 'string' || item === undefined);
+}
+function hasErrorCode(err, code) {
+    return isRecord(err) && err.code === code;
+}
+function copyEnvironment(env) {
+    // This assertion describes the empty dictionary we create, not external data.
+    return Object.assign(Object.create(null), env);
+}
+
+exports.copyEnvironment = copyEnvironment;
+exports.hasErrorCode = hasErrorCode;
+exports.isEnvironment = isEnvironment;
+exports.isRecord = isRecord;