updating-secrets 1.0.4 → 1.1.1

package/dist/adapters/base.adapter.d.ts

@@ -28,4 +28,6 @@ export declare class BaseSecretsAdapter {
      * any resources passed to it in its constructor.
      */
     destroy(): void;
+    /** Load an individual secret from the adapter. No shape checking is performed here. */
+    loadSingleSecret(secretId: string): MaybePromise<unknown>;
 }

package/dist/adapters/base.adapter.js

@@ -26,4 +26,9 @@ export class BaseSecretsAdapter {
      * any resources passed to it in its constructor.
      */
     destroy() { }
+    /** Load an individual secret from the adapter. No shape checking is performed here. */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    loadSingleSecret(secretId) {
+        throw new Error('Do not try to load a secret from the base secrets adapter.');
+    }
 }

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

@@ -1,5 +1,5 @@
 import { type MaybePromise, type PartialWithUndefined } from '@augment-vir/common';
-import { type SecretDefinitions, type SecretValues } from '../secrets-definition/define-secrets.js';
+import { type ProcessedSecretDefinitions, type SecretDefinitions, type SecretValues } from '../secrets-definition/define-secrets.js';
 import { BaseSecretsAdapter } from './base.adapter.js';
 /**
  * Options for {@link SecretsJsonFileAdapter}.
@@ -28,8 +28,10 @@ export type SecretsJsonFileAdapterOptions<Secrets extends SecretDefinitions = an
         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.
+     * Optional function that will automatically generate and save secrets if the JSON file is
+     * missing or if any secrets are missing. Only missing secrets will be added from the generated
+     * values; existing secrets are preserved. This is particularly useful for dev or testing
+     * environments where new secrets may be added over time.
      */
     generateValues: (() => MaybePromise<SecretValues<Secrets>>) | undefined;
 };
@@ -51,5 +53,7 @@ export declare class SecretsJsonFileAdapter<const Secrets extends SecretDefiniti
     /** Path to the JSON */
     jsonFilePath: string, options?: PartialWithUndefined<SecretsJsonFileAdapterOptions<Secrets>>);
     /** Loads secrets from the given JSON file path. */
-    loadSecrets(): Promise<any>;
+    loadSecrets(secrets: Readonly<ProcessedSecretDefinitions>): Promise<any>;
+    /** Load an individual secret from the JSON file. */
+    loadSingleSecret(secretKey: string): Promise<any>;
 }

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

@@ -1,7 +1,9 @@
+import { check } from '@augment-vir/assert';
 import { mergeDefinedProperties, parseWithJson5, } from '@augment-vir/common';
 import { existsSync as existsSyncImport } from 'node:fs';
 import { mkdir as mkDirImport, readFile as readFileImport, writeFile as writeFileImport, } from 'node:fs/promises';
 import { dirname } from 'node:path';
+import { checkValidShape } from 'object-shape-tester';
 import { BaseSecretsAdapter } from './base.adapter.js';
 const defaultSecretsJsonFileAdapterOptions = {
     fsOverride: {
@@ -35,20 +37,48 @@ export class SecretsJsonFileAdapter extends BaseSecretsAdapter {
         this.options = mergeDefinedProperties(defaultSecretsJsonFileAdapterOptions, options);
     }
     /** Loads secrets from the given JSON file path. */
-    async loadSecrets() {
-        if (!this.options.fsOverride.existsSync(this.jsonFilePath)) {
+    async loadSecrets(secrets) {
+        const fileExists = this.options.fsOverride.existsSync(this.jsonFilePath);
+        if (!fileExists) {
             if (this.options.generateValues) {
                 const newSecrets = await this.options.generateValues();
                 await this.options.fsOverride.promises.mkdir(dirname(this.jsonFilePath), {
                     recursive: true,
                 });
                 await this.options.fsOverride.promises.writeFile(this.jsonFilePath, JSON.stringify(newSecrets));
+                return 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);
+        const existingSecrets = parseWithJson5(fileContents);
+        if (this.options.generateValues) {
+            const invalidSecretKeys = Object.keys(secrets).filter((key) => {
+                if (!(key in existingSecrets)) {
+                    /** Secret is missing. */
+                    return true;
+                }
+                const secretValue = existingSecrets[key];
+                const shapeDefinition = secrets[key]?.shapeDefinition;
+                return shapeDefinition
+                    ? !checkValidShape(secretValue, shapeDefinition)
+                    : !check.isString(secretValue);
+            });
+            if (invalidSecretKeys.length > 0) {
+                const generatedSecrets = await this.options.generateValues();
+                invalidSecretKeys.forEach((invalidSecretKey) => {
+                    existingSecrets[invalidSecretKey] = generatedSecrets[invalidSecretKey];
+                });
+                await this.options.fsOverride.promises.writeFile(this.jsonFilePath, JSON.stringify(existingSecrets));
+            }
+        }
+        return existingSecrets;
+    }
+    /** Load an individual secret from the JSON file. */
+    async loadSingleSecret(secretKey) {
+        const fileContents = parseWithJson5(String(await this.options.fsOverride.promises.readFile(this.jsonFilePath)));
+        return fileContents[secretKey];
     }
 }

package/dist/adapters/static-secrets.adapter.d.ts

@@ -20,4 +20,6 @@ export declare class StaticSecretsAdapter extends BaseSecretsAdapter {
     staticSecrets: Record<string, JsonCompatibleValue>);
     /** Directly returns the static secrets given. */
     loadSecrets(): Record<string, JsonCompatibleValue>;
+    /** Load an individual secret from the static secrets given. */
+    loadSingleSecret(secretKey: string): JsonCompatibleValue;
 }

package/dist/adapters/static-secrets.adapter.js

@@ -23,4 +23,8 @@ export class StaticSecretsAdapter extends BaseSecretsAdapter {
     loadSecrets() {
         return this.staticSecrets;
     }
+    /** Load an individual secret from the static secrets given. */
+    loadSingleSecret(secretKey) {
+        return this.staticSecrets[secretKey];
+    }
 }

package/dist/updating-secrets.d.ts

@@ -1,5 +1,6 @@
 import { type PartialWithUndefined, type RequiredAndNotNull, type Values } from '@augment-vir/common';
-import { type AnyDuration } from 'date-vir';
+import { type AnyDuration, type FullDate } from 'date-vir';
+import { type Shape } from 'object-shape-tester';
 import { type BaseSecretsAdapter } from './adapters/base.adapter.js';
 import { type ProcessedSecretDefinitions, type RotatableSecretValue, type SecretDefinitions, type SecretValues } from './secrets-definition/define-secrets.js';
 /**
@@ -95,6 +96,12 @@ export declare class UpdatingSecrets<const Secrets extends Readonly<SecretDefini
      */
     protected loadingSecretsPromise: Promise<SecretValues<Secrets>> | undefined;
     protected consecutiveFailureCount: number;
+    protected dynamicCache: {
+        [SecretName in string]: {
+            value: any;
+            cachedAt: FullDate;
+        };
+    };
     constructor(secrets: Readonly<Secrets>, 
     /**
      * A list of adapters to load secrets from. Order here matters: all values loaded from the
@@ -173,6 +180,13 @@ export declare class UpdatingSecrets<const Secrets extends Readonly<SecretDefini
     actualRotatableSecretValue: RotatableSecretValue): boolean;
     /** Get the latest secret values. */
     get get(): SecretValues<Secrets>;
+    /**
+     * Load a single secret dynamically, without a secret definition. The given `secretKey` varies
+     * based on the adapters in use.
+     */
+    loadDynamicSecret<const S extends Shape>(secretKey: string, shapeRequirement: S): Promise<S['runtimeType']>;
+    /** Try to load a single secret from any of the provided adapters. */
+    protected loadSecretFromAdapters<const S extends Shape>(secretKey: string, shapeRequirement: S): Promise<S['runtimeType']>;
 }
 /**
  * Processes the given {@link SecretDefinitions} so they can be easily consumed by adapters. This is
@@ -187,6 +201,6 @@ export declare function processSecrets<const Secrets extends SecretDefinitions>(
         description: string;
         whereToFind: string;
     };
-    shapeDefinition: import("object-shape-tester").Shape | undefined;
+    shapeDefinition: Shape | undefined;
     adapterConfig: NonNullable<Values<SecretDefinitions>["adapterConfig"]>;
 }>;

package/dist/updating-secrets.js

@@ -1,7 +1,7 @@
 import { assert } from '@augment-vir/assert';
-import { combineErrors, DeferredPromise, ensureError, extractErrorMessage, getObjectTypedEntries, log, makeWritable, mapObject, mapObjectValues, mergeDefinedProperties, } from '@augment-vir/common';
-import { convertDuration } from 'date-vir';
-import { assertValidShape, defineShape } from 'object-shape-tester';
+import { combineErrors, DeferredPromise, ensureError, ensureErrorAndPrependMessage, extractErrorMessage, getObjectTypedEntries, log, makeWritable, mapObject, mapObjectValues, mergeDefinedProperties, } from '@augment-vir/common';
+import { calculateRelativeDate, convertDuration, getNowInUtcTimezone, isDateAfter, } from 'date-vir';
+import { assertValidShape, checkValidShape, defineShape } from 'object-shape-tester';
 import { SecretLoadError } from './secret-load.error.js';
 const defaultOptions = {
     lazyFailure: false,
@@ -59,6 +59,7 @@ export class UpdatingSecrets {
      */
     loadingSecretsPromise;
     consecutiveFailureCount = 0;
+    dynamicCache = {};
     constructor(secrets, 
     /**
      * A list of adapters to load secrets from. Order here matters: all values loaded from the
@@ -292,6 +293,45 @@ export class UpdatingSecrets {
         }
         return this.currentSecrets;
     }
+    /**
+     * Load a single secret dynamically, without a secret definition. The given `secretKey` varies
+     * based on the adapters in use.
+     */
+    async loadDynamicSecret(secretKey, shapeRequirement) {
+        const cached = this.dynamicCache[secretKey];
+        if (cached &&
+            checkValidShape(cached.value, shapeRequirement) &&
+            !isDateAfter({
+                fullDate: getNowInUtcTimezone(),
+                relativeTo: calculateRelativeDate(cached.cachedAt, this.options.updateInterval),
+            })) {
+            return cached.value;
+        }
+        const newValue = await this.loadSecretFromAdapters(secretKey, shapeRequirement);
+        this.dynamicCache[secretKey] = {
+            value: newValue,
+            cachedAt: getNowInUtcTimezone(),
+        };
+        return newValue;
+    }
+    /** Try to load a single secret from any of the provided adapters. */
+    async loadSecretFromAdapters(secretKey, shapeRequirement) {
+        const errors = [new Error(`Secret '${secretKey}' not found in any adapters.`)];
+        for (const adapter of this.adapters) {
+            try {
+                const value = await adapter.loadSingleSecret(secretKey);
+                if (!value) {
+                    throw new Error('Secret is empty');
+                }
+                assertValidShape(value, shapeRequirement);
+                return value;
+            }
+            catch (error) {
+                errors.push(ensureErrorAndPrependMessage(error, `Failed to load secret '${secretKey}' from adapter '${adapter.adapterName}'`));
+            }
+        }
+        throw combineErrors(errors);
+    }
 }
 /**
  * Processes the given {@link SecretDefinitions} so they can be easily consumed by adapters. This is

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "updating-secrets",
-    "version": "1.0.4",
+    "version": "1.1.1",
     "description": "Automatically update secrets on an interval with support for seamless secret rotation.",
     "keywords": [
         "secrets",
@@ -44,19 +44,19 @@
         "test:update": "npm run test update"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.40.0",
-        "@augment-vir/common": "^31.40.0",
-        "date-vir": "^8.0.0",
-        "object-shape-tester": "^6.9.2",
-        "type-fest": "^5.1.0"
+        "@augment-vir/assert": "^31.57.5",
+        "@augment-vir/common": "^31.57.5",
+        "date-vir": "^8.1.0",
+        "object-shape-tester": "^6.11.0",
+        "type-fest": "^5.3.1"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.40.0",
-        "@types/node": "^24.7.2",
+        "@augment-vir/test": "^31.57.5",
+        "@types/node": "^25.0.3",
         "c8": "^10.1.3",
         "istanbul-smart-text-reporter": "^1.1.5",
         "markdown-code-example-inserter": "^3.0.3",
-        "typedoc": "^0.28.14",
+        "typedoc": "^0.28.15",
         "typescript": "^5.9.3"
     },
     "engines": {