updating-secrets 0.0.1 → 0.1.0

package/README.md

@@ -2,6 +2,8 @@
 
 Automatically update secrets on an interval with support for seamless secret rotation.
 
+Reference docs: https://electrovir.github.io/updating-secrets
+
 ## Install
 
 ```sh

package/dist/adapters/secrets-json-file.adapter.d.ts

@@ -1,4 +1,34 @@
+import { type MaybePromise, type PartialWithUndefined } from '@augment-vir/common';
+import type { SecretDefinitions, SecretValues } from '../secrets-definition/define-secrets.js';
 import { BaseSecretsAdapter } from './base.adapter.js';
+/**
+ * Options for {@link SecretsJsonFileAdapter}.
+ *
+ * @category Internal
+ */
+export type SecretsJsonFileAdapterOptions<Secrets extends SecretDefinitions = any> = {
+    /**
+     * Optional override for Node.js's `fs` for mocking, testing, or other purposes.
+     *
+     * @default import * as fs from 'node:fs';
+     */
+    fsOverride: {
+        /** `'node:fs/promises'` */
+        promises: {
+            /** `readFile` from `'node:fs/promises'` */
+            readFile: (filePath: string) => Promise<string | Buffer>;
+            /** `writeFile` from `'node:fs/promises'` */
+            writeFile: (filePath: string, contents: string | Buffer) => Promise<void>;
+        };
+        /** `existsSync` from `'node:fs'` */
+        existsSync: (filePath: string) => boolean;
+    };
+    /**
+     * Optional function that will automatically generate and save new secrets if the JSON file is
+     * missing. This is particularly useful for dev or testing environments.
+     */
+    generateValues: (() => MaybePromise<SecretValues<Secrets>>) | undefined;
+};
 /**
  * Loads all secrets from a single JSON file. This should rarely be used in production environments.
  * Make sure that your secrets JSON file is not committed to your source code.
@@ -9,16 +39,13 @@ import { BaseSecretsAdapter } from './base.adapter.js';
  *
  * @category Adapters
  */
-export declare class SecretsJsonFileAdapter extends BaseSecretsAdapter {
+export declare class SecretsJsonFileAdapter<const Secrets extends SecretDefinitions = any> extends BaseSecretsAdapter {
     /** Path to the JSON */
     protected readonly jsonFilePath: string;
-    /** Optional override for `fs.promises.readFile` for mocking, testing, or other purposes. */
-    protected readonly readFileOverride: (filePath: string) => Promise<string | Buffer>;
+    protected readonly options: SecretsJsonFileAdapterOptions;
     constructor(
     /** Path to the JSON */
-    jsonFilePath: string, 
-    /** Optional override for `fs.promises.readFile` for mocking, testing, or other purposes. */
-    readFileOverride?: (filePath: string) => Promise<string | Buffer>);
+    jsonFilePath: string, options?: PartialWithUndefined<SecretsJsonFileAdapterOptions<Secrets>>);
     /** Loads secrets from the given JSON file path. */
     loadSecrets(): Promise<any>;
 }

package/dist/adapters/secrets-json-file.adapter.js

@@ -1,6 +1,17 @@
-import { parseWithJson5 } from '@augment-vir/common';
-import { readFile as readFileImport } from 'node:fs/promises';
+import { mergeDefinedProperties, parseWithJson5, } from '@augment-vir/common';
+import { existsSync as existsSyncImport } from 'node:fs';
+import { readFile as readFileImport, writeFile as writeFileImport } from 'node:fs/promises';
 import { BaseSecretsAdapter } from './base.adapter.js';
+const defaultSecretsJsonFileAdapterOptions = {
+    fsOverride: {
+        existsSync: existsSyncImport,
+        promises: {
+            readFile: readFileImport,
+            writeFile: writeFileImport,
+        },
+    },
+    generateValues: undefined,
+};
 /**
  * Loads all secrets from a single JSON file. This should rarely be used in production environments.
  * Make sure that your secrets JSON file is not committed to your source code.
@@ -13,19 +24,26 @@ import { BaseSecretsAdapter } from './base.adapter.js';
  */
 export class SecretsJsonFileAdapter extends BaseSecretsAdapter {
     jsonFilePath;
-    readFileOverride;
+    options;
     constructor(
     /** Path to the JSON */
-    jsonFilePath, 
-    /** Optional override for `fs.promises.readFile` for mocking, testing, or other purposes. */
-    readFileOverride = readFileImport) {
+    jsonFilePath, options = {}) {
         super('SecretsJsonFileAdapter');
         this.jsonFilePath = jsonFilePath;
-        this.readFileOverride = readFileOverride;
+        this.options = mergeDefinedProperties(defaultSecretsJsonFileAdapterOptions, options);
     }
     /** Loads secrets from the given JSON file path. */
     async loadSecrets() {
-        const fileContents = String(await this.readFileOverride(this.jsonFilePath));
+        if (!this.options.fsOverride.existsSync(this.jsonFilePath)) {
+            if (this.options.generateValues) {
+                const newSecrets = await this.options.generateValues();
+                await this.options.fsOverride.promises.writeFile(this.jsonFilePath, JSON.stringify(newSecrets));
+            }
+            else {
+                throw new Error(`Missing secrets JSON file at '${this.jsonFilePath}'`);
+            }
+        }
+        const fileContents = String(await this.options.fsOverride.promises.readFile(this.jsonFilePath));
         return parseWithJson5(fileContents);
     }
 }

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export * from './adapters/base.adapter.js';
 export * from './adapters/secrets-json-file.adapter.js';
 export * from './adapters/static-secrets.adapter.js';
 export * from './public-mocks/mock-aws-secrets-manager.js';
-export * from './public-mocks/mock-read-file.js';
+export * from './public-mocks/mock-fs.js';
 export * from './secret-load.error.js';
 export * from './secrets-definition/define-secrets.js';
 export * from './updating-secrets.js';

package/dist/index.js

@@ -4,7 +4,7 @@ export * from './adapters/base.adapter.js';
 export * from './adapters/secrets-json-file.adapter.js';
 export * from './adapters/static-secrets.adapter.js';
 export * from './public-mocks/mock-aws-secrets-manager.js';
-export * from './public-mocks/mock-read-file.js';
+export * from './public-mocks/mock-fs.js';
 export * from './secret-load.error.js';
 export * from './secrets-definition/define-secrets.js';
 export * from './updating-secrets.js';

package/dist/public-mocks/mock-fs.d.ts

@@ -0,0 +1,28 @@
+import type { MaybePromise } from '@augment-vir/common';
+import type { RequireExactlyOne } from 'type-fest';
+import { SecretsJsonFileAdapterOptions } from '../adapters/secrets-json-file.adapter.js';
+/**
+ * Mock data for {@link createMockFs}. There are two possible options contained herein, but only one
+ * may be used at a time.
+ *
+ * @category Internal
+ */
+export type FileMocks = RequireExactlyOne<{
+    /**
+     * This option specifies multiple files that can be read from the mocked `readFile` output of
+     * {@link createMockFs}. The keys of this object must _exactly_ match the file paths passed to
+     * the mock `readFile` output of {@link createMockFs}.
+     */
+    paths: {
+        [FilePath in string]: string | Buffer;
+    };
+    /** This option specifies the exact same output for any file path. */
+    contents: string | Buffer;
+}>;
+/**
+ * Mocks the built-in Node.js `fs.promises.readFile` method. See {@link FileMocks} for details on
+ * mocking strategies.
+ *
+ * @category Mocks
+ */
+export declare function createMockFs(mockFiles: FileMocks, writeFileMockCallback?: ((filePath: string, contents: string | Buffer) => MaybePromise<void>) | undefined): SecretsJsonFileAdapterOptions['fsOverride'];

package/dist/public-mocks/mock-fs.js

@@ -0,0 +1,47 @@
+/**
+ * Mocks the built-in Node.js `fs.promises.readFile` method. See {@link FileMocks} for details on
+ * mocking strategies.
+ *
+ * @category Mocks
+ */
+export function createMockFs(mockFiles, writeFileMockCallback) {
+    const writtenFiles = {};
+    return {
+        promises: {
+            readFile(filePath) {
+                if ('contents' in mockFiles) {
+                    return Promise.resolve(mockFiles.contents);
+                }
+                const contents = {
+                    ...mockFiles.paths,
+                    ...writtenFiles,
+                }[filePath];
+                if (contents == undefined) {
+                    const error = new Error(`ENOENT: no such file or directory, open '${filePath}'`);
+                    error.code = 'ENOENT';
+                    error.errno = -2;
+                    error.syscall = 'open';
+                    error.path = filePath;
+                    throw error;
+                }
+                else {
+                    return Promise.resolve(contents);
+                }
+            },
+            async writeFile(filePath, contents) {
+                if (writeFileMockCallback) {
+                    await writeFileMockCallback(filePath, contents);
+                }
+                writtenFiles[filePath] = contents;
+            },
+        },
+        existsSync(filePath) {
+            if ('contents' in mockFiles) {
+                return true;
+            }
+            else {
+                return filePath in mockFiles.paths;
+            }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "updating-secrets",
-    "version": "0.0.1",
+    "version": "0.1.0",
     "description": "Automatically update secrets on an interval with support for seamless secret rotation.",
     "keywords": [
         "secrets",

package/dist/public-mocks/mock-read-file.d.ts

@@ -1,26 +0,0 @@
-import type { RequireExactlyOne } from 'type-fest';
-/**
- * Mock data for {@link createMockReadFile}. There are two possible options contained herein, but
- * only one may be used at a time.
- *
- * @category Internal
- */
-export type ReadFileMocks = RequireExactlyOne<{
-    /**
-     * This option specifies multiple files that can be read from the mocked `readFile` output of
-     * {@link createMockReadFile}. The keys of this object must _exactly_ match the file paths passed
-     * to the mock `readFile` output of {@link createMockReadFile}.
-     */
-    paths: {
-        [FilePath in string]: string | Buffer;
-    };
-    /** This option specifies the exact same output for any file path. */
-    contents: string | Buffer;
-}>;
-/**
- * Mocks the built-in Node.js `fs.promises.readFile` method. See {@link ReadFileMocks} for details on
- * mocking strategies.
- *
- * @category Mocks
- */
-export declare function createMockReadFile(mock: ReadFileMocks): (path: string) => Promise<string | Buffer>;

package/dist/public-mocks/mock-read-file.js

@@ -1,25 +0,0 @@
-/**
- * Mocks the built-in Node.js `fs.promises.readFile` method. See {@link ReadFileMocks} for details on
- * mocking strategies.
- *
- * @category Mocks
- */
-export function createMockReadFile(mock) {
-    return (filePath) => {
-        if ('contents' in mock) {
-            return Promise.resolve(mock.contents);
-        }
-        const contents = mock.paths[filePath];
-        if (contents == undefined) {
-            const err = new Error(`ENOENT: no such file or directory, open '${filePath}'`);
-            err.code = 'ENOENT';
-            err.errno = -2;
-            err.syscall = 'open';
-            err.path = filePath;
-            throw err;
-        }
-        else {
-            return Promise.resolve(contents);
-        }
-    };
-}