@rezwanul7/settings 1.0.0 → 2.0.0

package/dist/index.d.ts

@@ -76,11 +76,43 @@ interface SettingsDefinition<T = unknown, SingleOwner extends boolean = boolean>
     /** Whether the Scope has exactly one Owner, stored with the id `"default"`. */
     readonly singleOwner: SingleOwner;
 }
+/** The settings type of a Settings definition. Internal: not exported from the package entry. */
+type SettingsOf<D> = D extends SettingsDefinition<infer T> ? T : never;
+/** Counts down the depth {@link NonJsonPaths} still walks, so a recursive settings type can't recurse forever. */
+type Depth = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+/** Whether an object type has a method, as a `Date`, `Map`, `Set` or class instance does. */
+type HasMethod<T> = true extends {
+    [K in keyof T]-?: 0 extends 1 & T[K] ? false : T[K] extends (...args: never[]) => unknown ? true : false;
+}[keyof T] ? true : false;
+/**
+ * The dot paths in `T` whose values can't be kept as JSON, such as a `Date`, `Map`, `Set`, `bigint` or class
+ * instance; `never` when every value can. An array's elements are named `path[]`. `unknown` and `any` pass, since
+ * the runtime check covers them, and so does anything deeper than the walk goes.
+ */
+type NonJsonPaths<T, P extends string, D extends number = 10> = [D] extends [
+    never
+] ? never : 0 extends 1 & T ? never : unknown extends T ? never : T extends string | number | boolean | null | undefined ? never : T extends bigint | symbol | ((...args: never[]) => unknown) ? P : T extends readonly (infer E)[] ? NonJsonPaths<E, `${P}[]`, Depth[D]> : T extends object ? HasMethod<T> extends true ? P : {
+    [K in keyof T & string]-?: NonJsonPaths<T[K], P extends "" ? K : `${P}.${K}`, Depth[D]>;
+}[keyof T & string] : P;
+/**
+ * Nothing extra when the schema's output can be kept as JSON. Otherwise a property no schema has, whose name states
+ * the rule and whose type names the offending paths, so the compile error at `schema` reads as the reason.
+ */
+type JsonOutputCheck<Schema extends StandardSchemaV1> = [
+    NonJsonPaths<StandardSchemaV1.InferOutput<Schema>, "">
+] extends [never] ? unknown : {
+    readonly "Not a JSON value, so it can't be stored at": NonJsonPaths<StandardSchemaV1.InferOutput<Schema>, ""> extends "" ? "(the whole settings)" : NonJsonPaths<StandardSchemaV1.InferOutput<Schema>, "">;
+};
 /**
  * Declares a Scope's Settings definition. The settings type is inferred from the schema's output type, and
  * `defaults` must be a complete value of it; optional schema fields may be left out. Any Standard Schema works, such
  * as one from Zod, Valibot or ArkType.
  *
+ * Overrides are kept as JSON, so a schema whose output has a value that isn't, such as a `Date` from
+ * `z.coerce.date()`, a `Map`, a `Set`, a `bigint` or a class instance, is a compile error at `schema` that names the
+ * path. Store a date as its string and convert it where the setting is used. Output typed `unknown` or `any` passes;
+ * writes still check their values at runtime.
+ *
  * The defaults are checked against the schema on the first operation on the Scope, because Standard Schema
  * validation may be async; `createSettings` throws `SettingsDefinitionError` there if they fail.
  *
@@ -88,27 +120,27 @@ interface SettingsDefinition<T = unknown, SingleOwner extends boolean = boolean>
  * @returns The Settings definition, to pass to `createSettings` under its Scope name.
  *
  * @example
- * const user = defineSettings({
+ * const userDefinition = defineSettings({
  *   schema: z.object({ theme: z.enum(["light", "dark"]), language: z.string() }),
  *   defaults: { theme: "light", language: "en" },
  * });
- * const global = defineSettings({
+ * const globalDefinition = defineSettings({
  *   schema: z.object({ maintenanceBanner: z.string().nullable() }),
  *   defaults: { maintenanceBanner: null },
  *   singleOwner: true,
  * });
  */
 declare function defineSettings<Schema extends StandardSchemaV1, SingleOwner extends boolean = false>(definition: {
-    /** The Standard Schema every Owner's Effective settings must pass. */
-    readonly schema: Schema;
+    /** The Standard Schema every Owner's Effective settings must pass. Its output must be JSON. */
+    readonly schema: Schema & JsonOutputCheck<Schema>;
     /** The complete settings used where an Owner has no Override. */
     readonly defaults: StandardSchemaV1.InferOutput<Schema>;
     /** `true` for a Scope with exactly one Owner, which takes no id. Defaults to `false`. */
     readonly singleOwner?: SingleOwner;
 }): SettingsDefinition<StandardSchemaV1.InferOutput<Schema>, SingleOwner>;
 
-/** Objects whose keys a dot path walks through; arrays, functions and dates are values, never walked into. */
-type Walkable<T> = T extends readonly unknown[] | Date | ((...args: never[]) => unknown) ? never : T extends object ? T : never;
+/** Objects whose keys a dot path walks through; arrays and functions are values, never walked into. */
+type Walkable<T> = T extends readonly unknown[] | ((...args: never[]) => unknown) ? never : T extends object ? T : never;
 /**
  * The union of dot paths through the nested plain objects of `T`, such as `"theme" | "notifications" |
  * "notifications.email"`. A path never descends into an array: an array is one value, set and reset as a whole.
@@ -128,11 +160,11 @@ type Path<T> = [Walkable<T>] extends [never] ? never : {
 type PathValue<T, P extends string> = P extends keyof Walkable<T> ? Walkable<T>[P] : P extends `${infer K}.${infer Rest}` ? K extends keyof Walkable<T> ? PathValue<NonNullable<Walkable<T>[K]>, Rest> | (null extends Walkable<T>[K] ? undefined : never) | (undefined extends Walkable<T>[K] ? undefined : never) : never : never;
 /**
  * A partial of `T` at any depth, for `update`: every key of a nested plain object may be left out or `undefined`.
- * Arrays, dates and functions are whole values, never partial.
+ * Arrays and functions are whole values, never partial.
  *
  * @typeParam T - The settings type.
  */
-type DeepPartial<T> = T extends readonly unknown[] | Date | ((...args: never[]) => unknown) ? T : T extends object ? {
+type DeepPartial<T> = T extends readonly unknown[] | ((...args: never[]) => unknown) ? T : T extends object ? {
     [K in keyof T]?: DeepPartial<T[K]> | undefined;
 } : T;
 
@@ -152,6 +184,10 @@ interface SettingsOptions<Definitions extends Record<string, SettingsDefinition>
      * next successful write drops them. Writes read the Overrides first, so it can also be called during a write, again
      * on each retry. Without it, ignored Overrides are dropped silently.
      *
+     * It isn't awaited, and it can't change the result of the read or write that calls it: if it throws or returns a
+     * rejected promise, the operation goes on as if it had succeeded, and the failure goes to `console.warn` the first
+     * time only for each {@link createSettings} result.
+     *
      * @param owner - The Owner whose Overrides were ignored.
      * @param issues - The Standard Schema issues the Effective settings failed with, naming the ignored paths.
      */
@@ -259,8 +295,6 @@ interface ScopedSettings<T> {
      */
     reset(): Promise<void>;
 }
-/** The settings type of a Settings definition. */
-type SettingsOf<D> = D extends SettingsDefinition<infer T> ? T : never;
 /** The id argument of `scope()`: none for a single-owner Scope, a string for any other. */
 type OwnerIdArgs<D> = D extends SettingsDefinition<unknown, true> ? [] : [id: string];
 /**
@@ -279,7 +313,10 @@ type OwnerIdArgs<D> = D extends SettingsDefinition<unknown, true> ? [] : [id: st
  * @throws `RangeError` If `maxRetries` isn't a whole number, 0 or more.
  *
  * @example
- * const settings = createSettings({ definitions: { user, global }, store: new MemoryStore() });
+ * const settings = createSettings({
+ *   definitions: { user: userDefinition, global: globalDefinition },
+ *   store: new MemoryStore(),
+ * });
  * const theme = await settings.scope("user", "1").get("theme");
  * await settings.scope("global").set("maintenanceBanner", "Back at 10:00");
  */
@@ -288,8 +325,11 @@ declare function createSettings<Definitions extends Record<string, SettingsDefin
      * Returns the settings of one Owner of the Scope `name`.
      *
      * @param name - The Scope name, a key of `definitions`.
-     * @param id - The Owner's id; left out for a single-owner Scope.
+     * @param id - The Owner's id, any non-empty string; left out for a single-owner Scope. The package doesn't interpret
+     *   it, so ids that differ in any way, such as `"1"` and `" 1"`, are different Owners.
      * @throws {@link SettingsDefinitionError} If `name` isn't a key of `definitions`.
+     * @throws `TypeError` If `id` is the empty string, is missing for a normal Scope, or is given for a single-owner
+     *   Scope.
      */
     scope<Name extends keyof Definitions & string>(name: Name, ...id: OwnerIdArgs<Definitions[Name]>): ScopedSettings<SettingsOf<Definitions[Name]>>;
 };
@@ -302,7 +342,7 @@ declare function createSettings<Definitions extends Record<string, SettingsDefin
  * write that read a version before a delete is a conflict; the Store remembers one number per Owner it ever stored.
  *
  * @example
- * const settings = createSettings({ definitions: { user }, store: new MemoryStore() });
+ * const settings = createSettings({ definitions: { user: userDefinition }, store: new MemoryStore() });
  */
 declare class MemoryStore implements SettingsStore {
     #private;
@@ -314,6 +354,230 @@ declare class MemoryStore implements SettingsStore {
     delete(owner: Owner): Promise<void>;
 }
 
+/**
+ * The part of a Secret Vault `Vault` that {@link SealedStore} uses, so this package doesn't depend on Secret Vault.
+ * A `Vault` fits.
+ */
+interface SealingVault {
+    /**
+     * Seals a JSON value.
+     *
+     * @param value - The value to seal.
+     * @param context - Where the Sealed value is stored.
+     * @returns The Sealed value.
+     */
+    encryptJson(value: unknown, context: string): Promise<string>;
+    /**
+     * Opens a Sealed value made by `encryptJson`; rejects when it doesn't open.
+     *
+     * @param sealed - The Sealed value.
+     * @param context - The Context it was sealed under.
+     * @returns The Plaintext value.
+     */
+    decryptJson(sealed: string, context: string): Promise<unknown>;
+    /**
+     * Whether a stored value is a Sealed value rather than plain text still stored at a listed path. Optional: a Secret
+     * Vault `Vault` has `isSealed` only as a static method, so without it `SealedStore` treats a string starting with
+     * `vault:` as sealed.
+     *
+     * @param value - A stored value.
+     */
+    isSealed?(value: unknown): boolean;
+}
+/**
+ * The paths to keep sealed, by Scope name, each checked against its Scope's settings type, such as
+ * `{ organization: ["smtp.password"] }`. A Scope may be left out.
+ *
+ * @typeParam Definitions - The Settings definitions by Scope name.
+ */
+type SealedPaths<Definitions extends Record<string, SettingsDefinition>> = {
+    readonly [Scope in keyof Definitions & string]?: readonly Path<SettingsOf<Definitions[Scope]>>[];
+};
+/**
+ * Options of {@link SealedStore}.
+ *
+ * @typeParam Definitions - The Settings definitions by Scope name, the same ones passed to `createSettings`.
+ */
+interface SealedStoreOptions<Definitions extends Record<string, SettingsDefinition>> {
+    /** The Store that keeps the Sealed values. */
+    readonly store: SettingsStore;
+    /** Seals and opens values; a Secret Vault `Vault` fits. */
+    readonly vault: SealingVault;
+    /**
+     * Each Scope's Settings definition, by Scope name: the same object passed to `createSettings`. Only used to check
+     * `paths`.
+     */
+    readonly definitions: Definitions;
+    /**
+     * Dot paths into the settings to keep sealed, by Scope name, such as `{ organization: ["smtp.password"] }`. A path
+     * may name an object, which is sealed whole as JSON. No path may be inside another of the same Scope; two Scopes may
+     * list the same path. A Scope left out has nothing sealed: a Sealed value stored there reads back as its raw
+     * `vault:…` string.
+     */
+    readonly paths: NoInfer<SealedPaths<Definitions>>;
+}
+/**
+ * A Store that keeps the Overrides at the listed paths as Sealed values in the Store it wraps, and hands the core
+ * their Plaintext. The schema validates the Plaintext, and the app calls `set` and `get` with plain values.
+ *
+ * Every write seals again with the Vault's current secret, which finishes a Rotation for that Owner. A Sealed value
+ * that doesn't open makes the read throw: it is never ignored as a stale Override, because the next write would
+ * replace the secret with its default. A plain value at a listed path reads as it is and is sealed on the Owner's next
+ * write. Values at unlisted paths are never opened.
+ *
+ * Paths are listed per Scope and checked against each Scope's settings type, so a misspelled path doesn't compile. Only
+ * the paths listed for an Owner's Scope are sealed and opened; the same path in another Scope stays plain.
+ *
+ * Nest it outermost, around a {@link CachedStore}, so the cache holds only Sealed values.
+ *
+ * @typeParam Definitions - The Settings definitions by Scope name.
+ *
+ * @example
+ * const store = new SealedStore({
+ *   store: new PrismaStore({ delegate: prisma.setting }),
+ *   vault,
+ *   definitions: { user, organization },
+ *   paths: { organization: ["smtp.password"] },
+ * });
+ */
+declare class SealedStore<Definitions extends Record<string, SettingsDefinition> = Record<string, SettingsDefinition>> implements SettingsStore {
+    #private;
+    /**
+     * @param options - The Store to wrap, the Vault, the Settings definitions and the sealed paths by Scope.
+     * @throws `TypeError` when no Scope lists a path, a Scope in `paths` isn't in `definitions`, a path is empty, or a
+     *   path is inside another of the same Scope.
+     */
+    constructor(options: SealedStoreOptions<Definitions>);
+    /** {@inheritDoc SettingsStore.read} */
+    read(owner: Owner): Promise<StoredOverrides | null>;
+    /** {@inheritDoc SettingsStore.write} */
+    write(owner: Owner, overrides: Record<string, unknown>, expectedVersion: number | null): Promise<number | null>;
+    /**
+     * Removes one Sealed value that won't open, so the Owner can read its settings and set a new secret again; its
+     * other Sealed values stay sealed and aren't opened, and a plain value at another listed path is sealed, as on any
+     * write. Its other Overrides stay as they are. A value that opens, a
+     * plain value and an empty path are left alone, so running it again after the Owner set a new secret changes
+     * nothing. Any rejection from `decryptJson` counts as not opening.
+     *
+     * **Check the Vault secret first.** With a wrong or missing secret every Sealed value fails to open, so `discard`
+     * would remove secrets that fixing the configuration would have recovered.
+     *
+     * It reads the wrapped Store and writes with the version it read. On a conflict it reads again and retries, up to 3
+     * times; a {@link CachedStore} underneath evicts on the conflict, so the retry reads fresh Overrides.
+     *
+     * @param owner - The Owner whose Sealed value to remove.
+     * @param path - A path listed for the Owner's Scope, such as `"smtp.password"`.
+     * @returns `true` when a Sealed value that won't open was removed, `false` when nothing was changed.
+     * @throws `TypeError` when `path` isn't listed for the Owner's Scope.
+     * @throws {@link SettingsConflictError} when every write lost the version race to another write.
+     */
+    discard(owner: Owner, path: string): Promise<boolean>;
+    /** {@inheritDoc SettingsStore.delete} */
+    delete(owner: Owner): Promise<void>;
+}
+
+/**
+ * A cache of strings with a time to live, which {@link CachedStore} keeps Overrides in. {@link MemoryCache} fits;
+ * so does a thin wrapper around Redis or Keyv.
+ */
+interface SettingsCache {
+    /**
+     * Reads an entry.
+     *
+     * @param key - The cache key.
+     * @returns The value, or `undefined` when there is none or it expired.
+     */
+    get(key: string): Promise<string | undefined>;
+    /**
+     * Stores an entry, replacing any under the key.
+     *
+     * @param key - The cache key.
+     * @param value - The string to keep.
+     * @param ttlSeconds - Seconds until the entry expires.
+     */
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    /**
+     * Removes an entry; removing a missing one does nothing.
+     *
+     * @param key - The cache key.
+     */
+    delete(key: string): Promise<void>;
+}
+/** Options of {@link CachedStore}. */
+interface CachedStoreOptions {
+    /** The Store to read through. */
+    readonly store: SettingsStore;
+    /** Where to keep what the Store returns. */
+    readonly cache: SettingsCache;
+    /** Seconds an entry stays cached. */
+    readonly ttl: number;
+    /** Starts every cache key. Defaults to `"settings"`. */
+    readonly prefix?: string;
+    /**
+     * Called with an error a cache method threw; the Store then answers instead.
+     *
+     * It isn't awaited, and it can't change the result of the read, write or delete that calls it: if it throws or
+     * returns a rejected promise, the operation goes on as if it had succeeded, so a write still returns the wrapped
+     * Store's result. The failure goes to `console.warn` the first time only for each {@link CachedStore}.
+     */
+    readonly onError?: (error: unknown) => void;
+}
+/**
+ * A Store that keeps what the Store it wraps returns in a cache for `ttl` seconds, an Owner with nothing stored
+ * included. Every write, conflict and delete evicts the Owner, so a conflicting write retries against fresh Overrides,
+ * and a write on this instance is read back at once by this instance, even when one of its reads of that Owner was in
+ * flight during the write: a read that an eviction overtook returns what it read but doesn't cache it. A cache that
+ * throws is reported to `onError` and the Store answers instead.
+ *
+ * With a per-process cache and several instances, another instance can read Overrides up to `ttl` seconds old. Share
+ * a cache, such as Redis, to avoid most of it. Even then, a read on another instance that was in flight during the
+ * write can still cache the old Overrides, which are then read for up to `ttl` seconds.
+ *
+ * @example
+ * const store = new CachedStore({ store: prismaStore, cache: new MemoryCache(), ttl: 60 });
+ */
+declare class CachedStore implements SettingsStore {
+    #private;
+    /**
+     * @param options - The Store to wrap, the cache and the TTL.
+     * @throws `RangeError` when `ttl` isn't a positive number.
+     */
+    constructor(options: CachedStoreOptions);
+    /** {@inheritDoc SettingsStore.read} */
+    read(owner: Owner): Promise<StoredOverrides | null>;
+    /** {@inheritDoc SettingsStore.write} */
+    write(owner: Owner, overrides: Record<string, unknown>, expectedVersion: number | null): Promise<number | null>;
+    /** {@inheritDoc SettingsStore.delete} */
+    delete(owner: Owner): Promise<void>;
+}
+
+/** Options of {@link MemoryCache}. */
+interface MemoryCacheOptions {
+    /** Most entries kept; the oldest are evicted past it. Defaults to 1000. */
+    readonly maxEntries?: number;
+}
+/**
+ * A {@link SettingsCache} in process memory. Entries expire after their TTL and the oldest are evicted past
+ * `maxEntries`. It is per process: instances don't share it.
+ *
+ * @example
+ * const cache = new MemoryCache({ maxEntries: 5000 });
+ */
+declare class MemoryCache implements SettingsCache {
+    #private;
+    /**
+     * @param options - The size limit.
+     * @throws `RangeError` when `maxEntries` isn't a positive integer.
+     */
+    constructor(options?: MemoryCacheOptions);
+    /** {@inheritDoc SettingsCache.get} */
+    get(key: string): Promise<string | undefined>;
+    /** {@inheritDoc SettingsCache.set} */
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    /** {@inheritDoc SettingsCache.delete} */
+    delete(key: string): Promise<void>;
+}
+
 /**
  * A write would make an Owner's Effective settings fail its Scope's schema, so nothing was stored. `issues` are the
  * Standard Schema issues, with paths into the Effective settings, for showing next to a form field.
@@ -358,4 +622,4 @@ declare class SettingsDefinitionError extends Error {
     constructor(message: string, scope: string, issues?: ReadonlyArray<StandardSchemaV1.Issue>);
 }
 
-export { MemoryStore, Owner, type Path, type PathValue, type ScopedSettings, SettingsConflictError, type SettingsDefinition, SettingsDefinitionError, type SettingsOptions, SettingsStore, SettingsValidationError, StoredOverrides, createSettings, defineSettings };
+export { CachedStore, type CachedStoreOptions, MemoryCache, type MemoryCacheOptions, MemoryStore, Owner, type Path, type PathValue, type ScopedSettings, type SealedPaths, SealedStore, type SealedStoreOptions, type SealingVault, type SettingsCache, SettingsConflictError, type SettingsDefinition, SettingsDefinitionError, type SettingsOptions, SettingsStore, SettingsValidationError, StoredOverrides, createSettings, defineSettings };