@rezwanul7/settings 0.0.0-stage → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,348 @@
+import { O as Owner, S as SettingsStore, a as StoredOverrides } from './store-B4pWek75.cjs';
+
+/** The Standard Schema interface. */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    /** The Standard Schema properties. */
+    readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+    /** The Standard Schema properties interface. */
+    interface Props<Input = unknown, Output = Input> {
+        /** The version number of the standard. */
+        readonly version: 1;
+        /** The vendor name of the schema library. */
+        readonly vendor: string;
+        /** Validates unknown input values. */
+        readonly validate: (value: unknown, options?: StandardSchemaV1.Options | undefined) => Result<Output> | Promise<Result<Output>>;
+        /** Inferred types associated with the schema. */
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    /** The result interface of the validate function. */
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    /** The result interface if validation succeeds. */
+    interface SuccessResult<Output> {
+        /** The typed output value. */
+        readonly value: Output;
+        /** A falsy value for `issues` indicates success. */
+        readonly issues?: undefined;
+    }
+    /** The options for the validate function. */
+    interface Options {
+        /** Explicit support for additional vendor-specific parameters, if needed. */
+        readonly libraryOptions?: Record<string, unknown> | undefined;
+    }
+    /** The result interface if validation fails. */
+    interface FailureResult {
+        /** The issues of failed validation. */
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    /** The issue interface of the failure output. */
+    interface Issue {
+        /** The error message of the issue. */
+        readonly message: string;
+        /** The path of the issue, if any. */
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    /** The path segment interface of the issue. */
+    interface PathSegment {
+        /** The key representing a path segment. */
+        readonly key: PropertyKey;
+    }
+    /** The Standard Schema types interface. */
+    interface Types<Input = unknown, Output = Input> {
+        /** The input type of the schema. */
+        readonly input: Input;
+        /** The output type of the schema. */
+        readonly output: Output;
+    }
+    /** Infers the input type of a Standard Schema. */
+    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+    /** Infers the output type of a Standard Schema. */
+    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+
+/**
+ * A Scope's schema and its defaults: the shape every Owner's Effective settings must have, and the values used where
+ * an Owner has no Override. Create one with {@link defineSettings}.
+ *
+ * @typeParam T - The settings type: the schema's output type.
+ * @typeParam SingleOwner - `true` for a single-owner Scope, such as `global`, whose one Owner takes no id.
+ */
+interface SettingsDefinition<T = unknown, SingleOwner extends boolean = boolean> {
+    /** The Standard Schema every Owner's Effective settings must pass. */
+    readonly schema: StandardSchemaV1<unknown, T>;
+    /** The complete settings used where an Owner has no Override. */
+    readonly defaults: T;
+    /** Whether the Scope has exactly one Owner, stored with the id `"default"`. */
+    readonly singleOwner: SingleOwner;
+}
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * @param definition - The schema, the defaults, and `singleOwner: true` for a Scope with exactly one Owner.
+ * @returns The Settings definition, to pass to `createSettings` under its Scope name.
+ *
+ * @example
+ * const user = defineSettings({
+ *   schema: z.object({ theme: z.enum(["light", "dark"]), language: z.string() }),
+ *   defaults: { theme: "light", language: "en" },
+ * });
+ * const global = 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 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;
+/**
+ * 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.
+ *
+ * @typeParam T - The settings type.
+ */
+type Path<T> = [Walkable<T>] extends [never] ? never : {
+    [K in keyof Walkable<T> & string]-?: K | `${K}.${Path<NonNullable<Walkable<T>[K]>>}`;
+}[keyof Walkable<T> & string];
+/**
+ * The type of the value at dot path `P` in `T`. A path through an optional or nullable object can find nothing, so
+ * its value type includes `undefined`.
+ *
+ * @typeParam T - The settings type.
+ * @typeParam P - A dot path, one of {@link Path}.
+ */
+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.
+ *
+ * @typeParam T - The settings type.
+ */
+type DeepPartial<T> = T extends readonly unknown[] | Date | ((...args: never[]) => unknown) ? T : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]> | undefined;
+} : T;
+
+/**
+ * Options for {@link createSettings}.
+ *
+ * @typeParam Definitions - The Settings definitions by Scope name.
+ */
+interface SettingsOptions<Definitions extends Record<string, SettingsDefinition>> {
+    /** Each Scope's Settings definition, by Scope name, such as `{ user, global }`. */
+    readonly definitions: Definitions;
+    /** Where the Overrides are kept. */
+    readonly store: SettingsStore;
+    /**
+     * Called when stored Overrides fail the current schema, for example after an enum value was renamed, or are keys the
+     * schema no longer knows, and are ignored so their defaults apply. The stored document isn't changed by a read; the
+     * 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.
+     *
+     * @param owner - The Owner whose Overrides were ignored.
+     * @param issues - The Standard Schema issues the Effective settings failed with, naming the ignored paths.
+     */
+    readonly onInvalid?: (owner: Owner, issues: ReadonlyArray<StandardSchemaV1.Issue>) => void;
+    /**
+     * How many times a write that lost the version race to another write re-reads the Overrides and applies its change
+     * again before it throws {@link SettingsConflictError}. A whole number, 0 or more; 0 never retries.
+     *
+     * @defaultValue 3
+     */
+    readonly maxRetries?: number;
+}
+/**
+ * Reads and writes one Owner's settings. Get one from `settings.scope(name, id)`.
+ *
+ * A stored Override that fails the current schema, or a stored key the schema no longer knows, is ignored on read so
+ * its default applies, and is reported to `onInvalid`; the stored document isn't changed by a read.
+ *
+ * Every write reads the Owner's Overrides, drops the ones a read would ignore, applies the change, validates the
+ * Effective settings the change produces against the Scope's schema, and stores the Overrides with the version it
+ * read. Only that result is validated, so a write that repairs Effective settings a read throws
+ * {@link SettingsDefinitionError} for succeeds. If another write stored a newer version in between, it reads again
+ * and applies its change to the newer Overrides, so concurrent writes to different settings are all kept. What is
+ * stored is the change as given, not the schema's output.
+ *
+ * The keys `__proto__`, `constructor` and `prototype` can't be setting names: a write with one in its path or value
+ * throws {@link SettingsValidationError} with a `"Forbidden key"` issue, and `get(path)` reads one as `undefined`.
+ *
+ * @typeParam T - The Scope's settings type.
+ */
+interface ScopedSettings<T> {
+    /** The Owner these settings belong to. */
+    readonly owner: Owner;
+    /**
+     * Reads the Owner's Effective settings: the Scope's defaults with the Owner's Overrides deep-merged over them.
+     * Plain objects merge key by key; arrays, scalars and `null` replace the default. Overrides that fail the schema
+     * are ignored and reported to `onInvalid`.
+     *
+     * @returns The complete Effective settings, as the schema outputs them.
+     * @throws {@link SettingsDefinitionError} If the Scope's defaults fail its schema, or the Effective settings still
+     *   fail it after ignoring the invalid Overrides.
+     */
+    get(): Promise<T>;
+    /**
+     * Reads one value of the Owner's Effective settings.
+     *
+     * @param path - A dot path into the settings, such as `"notifications.email"`.
+     * @returns The Effective value at `path`.
+     * @throws {@link SettingsDefinitionError} If the Scope's defaults or the Effective settings fail its schema.
+     */
+    get<P extends Path<T>>(path: P): Promise<PathValue<T, P>>;
+    /**
+     * Stores `value` as the Owner's Override at `path`, keeping its other Overrides. A value equal to the default is
+     * still stored, so a later change of the default doesn't change what the Owner chose.
+     *
+     * @param path - A dot path into the settings, such as `"notifications.email"`.
+     * @param value - The value to store at `path`.
+     * @throws {@link SettingsValidationError} If the Effective settings with the change fail the schema, or the change has
+     *   a key the schema doesn't know, reported as an `"Unknown setting"` issue; nothing is stored.
+     * @throws {@link SettingsConflictError} If other writes to the Owner kept winning the version race for `maxRetries`
+     *   retries; nothing is stored.
+     */
+    set<P extends Path<T>>(path: P, value: PathValue<T, P>): Promise<void>;
+    /**
+     * Changes several settings at once by deep-merging `partial` into the Owner's Overrides: plain objects merge key by
+     * key; arrays, scalars and `null` replace. An `undefined` value leaves that Override as it was, while `null` is
+     * stored as a value and passes only if the schema allows it.
+     *
+     * @param partial - The settings to change, at any depth, such as `{ theme: "dark", notifications: { email: false } }`.
+     * @throws {@link SettingsValidationError} If the Effective settings with the change fail the schema, or `partial` has
+     *   a key the schema doesn't know, reported as an `"Unknown setting"` issue; nothing is stored.
+     * @throws {@link SettingsConflictError} If other writes to the Owner kept winning the version race for `maxRetries`
+     *   retries; nothing is stored.
+     */
+    update(partial: DeepPartial<T>): Promise<void>;
+    /**
+     * Reads the Owner's Overrides as stored, without the defaults, for example to show which values are the Owner's
+     * own choices. Overrides a read would ignore are included until the next write drops them.
+     *
+     * @returns The stored Overrides, or `{}` when nothing is stored.
+     */
+    getOverrides(): Promise<Record<string, unknown>>;
+    /**
+     * Removes the Override at `path`, so that setting follows the default again. Resetting an object removes every
+     * Override under it. With no Override at or under `path`, it writes nothing.
+     *
+     * @param path - A dot path into the settings.
+     * @throws {@link SettingsValidationError} If the Effective settings without the Override fail the schema.
+     * @throws {@link SettingsConflictError} If other writes to the Owner kept winning the version race for `maxRetries`
+     *   retries; nothing is stored.
+     */
+    reset(path: Path<T>): Promise<void>;
+    /**
+     * Deletes everything stored for the Owner, so it reads the defaults. Use it to clean up when the Owner is deleted.
+     */
+    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];
+/**
+ * Creates the settings for an app's Scopes over one Store. Call `scope(name, id)` on the result to read and write
+ * one Owner's settings; a single-owner Scope takes no id.
+ *
+ * Each Scope's defaults are validated against its schema on the first operation on that Scope, and the outcome is
+ * kept for the life of the returned object. If the validation itself throws, such as an async validator that can't
+ * reach its service, that operation rejects with the error and the next one checks again.
+ *
+ * @param options - The Settings definitions by Scope name, the Store, and how often a conflicting write retries.
+ * @returns An object whose `scope(name, id)` returns the {@link ScopedSettings} of one Owner.
+ * @throws `RangeError` If `maxRetries` isn't a whole number, 0 or more.
+ *
+ * @example
+ * const settings = createSettings({ definitions: { user, global }, store: new MemoryStore() });
+ * const theme = await settings.scope("user", "1").get("theme");
+ * await settings.scope("global").set("maintenanceBanner", "Back at 10:00");
+ */
+declare function createSettings<Definitions extends Record<string, SettingsDefinition>>(options: SettingsOptions<Definitions>): {
+    /**
+     * 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.
+     * @throws {@link SettingsDefinitionError} If `name` isn't a key of `definitions`.
+     */
+    scope<Name extends keyof Definitions & string>(name: Name, ...id: OwnerIdArgs<Definitions[Name]>): ScopedSettings<SettingsOf<Definitions[Name]>>;
+};
+
+/**
+ * A Store in process memory, for tests and prototypes. It keeps Overrides as JSON, the way a database's JSON column
+ * does, so a value that isn't JSON, such as a `Date`, reads back as its JSON form here too. It copies Overrides on the
+ * way in and out, so callers can't change what is stored by mutating an object they passed or got back. Its contents
+ * are lost when the process exits and aren't shared between processes. Versions keep increasing across `delete`, so a
+ * 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() });
+ */
+declare class MemoryStore implements SettingsStore {
+    #private;
+    /** {@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>;
+}
+
+/**
+ * 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.
+ */
+declare class SettingsValidationError extends Error {
+    /** The Standard Schema issues the Effective settings failed with. */
+    readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
+    /**
+     * @param issues - The Standard Schema issues.
+     */
+    constructor(issues: ReadonlyArray<StandardSchemaV1.Issue>);
+}
+/**
+ * A write kept losing the version race: other writes to the same Owner changed its Overrides every time it re-read
+ * them and applied its change again, until `maxRetries` retries were used up. Nothing was stored for this write. It
+ * is safe to try the whole write again later.
+ */
+declare class SettingsConflictError extends Error {
+    /** The Owner whose Overrides couldn't be written. */
+    readonly owner: Owner;
+    /**
+     * @param owner - The Owner whose Overrides couldn't be written.
+     * @param retries - How many times the write re-read and applied its change again.
+     */
+    constructor(owner: Owner, retries: number);
+}
+/**
+ * A Scope can't be used as defined: its name isn't in `definitions`, or its defaults, or an Owner's Effective
+ * settings, fail its schema. This is a bug in the app's Settings definitions, not in the input, so it isn't meant to
+ * be shown to a user.
+ */
+declare class SettingsDefinitionError extends Error {
+    /** The Scope name the error is about. */
+    readonly scope: string;
+    /** The Standard Schema issues, when the error is a failed validation. */
+    readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
+    /**
+     * @param message - The error message.
+     * @param scope - The Scope name.
+     * @param issues - The Standard Schema issues, if any.
+     */
+    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 };