@rezwanul7/settings 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rezwanul Islam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,389 @@
-# Temporary Holding Version
+# @rezwanul7/settings
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Per-user and app-wide settings for an app, such as a user's theme and language or a global maintenance banner. Each
+Scope declares a schema and its defaults once; only an Owner's own choices, its Overrides, are stored, as one JSON
+document per Owner, and every read returns the Effective settings: the defaults with the Overrides applied. Adding a
+field or changing a default needs no migration of stored rows. Writes are validated and guarded by a version, so two
+requests changing one Owner's settings at once both take effect. The terms used here are defined in the package
+[glossary](./GLOSSARY.md).
+
+## Installation
+
+```bash
+npm install @rezwanul7/settings
+# or
+pnpm add @rezwanul7/settings
+```
+
+The package has no runtime or peer dependencies. Schemas can come from any validator that implements
+[Standard Schema](https://standardschema.dev), such as Zod, Valibot or ArkType; the examples use Zod.
+
+## Entry points
+
+| Import                       | Contents                                                                   |
+| ---------------------------- | -------------------------------------------------------------------------- |
+| `@rezwanul7/settings`        | `defineSettings`, `createSettings`, `MemoryStore`, every type and error    |
+| `@rezwanul7/settings/prisma` | `PrismaStore` and the delegate type it accepts; doesn't need Prisma itself |
+
+## Defining Scopes
+
+A Scope is a kind of Owner, such as `user` or `organization`. Give each Scope one Settings definition with
+`defineSettings`: a schema and the defaults used wherever an Owner has no Override. The settings type is inferred from
+the schema's output type, and `defaults` must be a complete value of it; optional fields may be left out.
+
+A single-owner Scope, such as `global` for app-wide settings, has exactly one Owner. Mark it with `singleOwner: true`.
+
+```ts
+// src/server/settings-definitions.ts
+import { defineSettings } from "@rezwanul7/settings";
+import { z } from "zod";
+
+export const user = defineSettings({
+  schema: z.object({
+    theme: z.enum(["light", "dark", "system"]),
+    language: z.string(),
+    notifications: z.object({ email: z.boolean(), push: z.boolean() }),
+  }),
+  defaults: {
+    theme: "system",
+    language: "en",
+    notifications: { email: true, push: false },
+  },
+});
+
+export const global = defineSettings({
+  schema: z.object({ maintenanceBanner: z.string().nullable() }),
+  defaults: { maintenanceBanner: null },
+  singleOwner: true,
+});
+```
+
+The defaults are checked against the schema on the first operation on each Scope, because Standard Schema validation
+may be async. Defaults that fail it throw `SettingsDefinitionError` there, on every operation on that Scope. 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.
+
+### Keep the schema's output valid input
+
+Every read merges the Overrides over the defaults and validates the result, and every write validates the Effective
+settings it would produce. What is stored is the change as given, not the schema's output. So the defaults, which have
+the output type, and the stored Overrides are validated again on every read, and a schema whose output doesn't pass
+the schema again breaks:
+
+- Don't use transforms that change a value's type, such as a string parsed into a `Date`: the defaults (a `Date`)
+  would then fail the schema, which expects a string. A transform that keeps the type, such as trimming, works, but
+  runs on every read rather than once on write.
+- Don't use schema-level defaults, such as Zod's `.default()`. The Settings definition's `defaults` are the one place
+  defaults live, and every field already has one there.
+- Use only JSON values: strings, finite numbers, booleans, `null`, arrays and plain objects. Every Store keeps the
+  Overrides as JSON, so a `Date` would read back as its ISO string and an `undefined` value would be dropped. For a
+  date, store the string and convert it where the setting is used. `MemoryStore` keeps them as JSON too, so tests
+  show what a database does.
+
+## Creating the settings
+
+Pass every Settings definition, by Scope name, and a Store to `createSettings`. Then `scope(name, id)` gives one
+Owner's `ScopedSettings`. Owner ids are strings. A single-owner Scope takes no id; any other Scope requires one, and
+both rules are checked by the types.
+
+```ts
+import { createSettings, MemoryStore } from "@rezwanul7/settings";
+import { global, user } from "./settings-definitions";
+
+const settings = createSettings({
+  definitions: { user, global },
+  store: new MemoryStore(),
+  onInvalid: (owner, issues) => {
+    console.warn("Ignored stale settings", owner, issues);
+  },
+  maxRetries: 3,
+});
+
+const userSettings = settings.scope("user", "42");
+const globalSettings = settings.scope("global");
+```
+
+| Option        | Default    | What it does                                                                                                     |
+| ------------- | ---------- | ---------------------------------------------------------------------------------------------------------------- |
+| `definitions` | (required) | Each Scope's Settings definition, by Scope name.                                                                 |
+| `store`       | (required) | Where the Overrides are kept: `MemoryStore`, `PrismaStore` or your own `SettingsStore`.                          |
+| `onInvalid`   | none       | Called with the Owner and the issues when stored Overrides are ignored; see [Stale Overrides](#stale-overrides). |
+| `maxRetries`  | `3`        | How often a write that lost a version race tries again; see [Concurrent writes](#concurrent-writes).             |
+
+`maxRetries` must be a whole number, 0 or more, or `createSettings` throws a `RangeError`. With `0`, a write never
+retries.
+
+`MemoryStore` keeps Overrides in process memory, for tests and prototypes; they are lost when the process exits and
+aren't shared between processes. For a database, use the [Prisma Store](#storing-settings-with-prisma) or implement
+`SettingsStore` (its contract is in the [API reference](./docs/api/README.md#settingsstore)).
+
+## Reading and writing an Owner's settings
+
+```ts
+const me = settings.scope("user", "42");
+
+await me.get(); // { theme: "system", language: "en", notifications: { email: true, push: false } }
+await me.get("notifications.email"); // true
+
+await me.set("theme", "dark");
+await me.update({ language: "de", notifications: { push: true } });
+await me.getOverrides(); // { theme: "dark", language: "de", notifications: { push: true } }
+
+await me.reset("theme"); // theme follows the default again
+await me.reset(); // deletes everything stored for the Owner
+```
+
+| Member             | What it does                                                                                |
+| ------------------ | ------------------------------------------------------------------------------------------- |
+| `owner`            | The Owner, `{ scope, id }`. The Owner of a single-owner Scope has the id `"default"`.       |
+| `get()`            | The complete Effective settings, as the schema outputs them.                                |
+| `get(path)`        | One typed value of the Effective settings, at a dot path such as `"notifications.email"`.   |
+| `set(path, value)` | Stores `value` as the Override at `path`, keeping the other Overrides.                      |
+| `update(partial)`  | Deep-merges `partial` into the Overrides, to change several settings at once.               |
+| `getOverrides()`   | The Overrides as stored, without the defaults, or `{}` when nothing is stored.              |
+| `reset(path)`      | Removes the Override at `path` (and every Override under it), so the default applies again. |
+| `reset()`          | Deletes everything stored for the Owner, so it reads the defaults.                          |
+
+- Paths and values are type-checked: `set("theme", "blue")` and `get("colour")` don't compile. A path never goes into
+  an array; an array is one value, set and reset as a whole.
+- `__proto__`, `constructor` and `prototype` can't be setting names, at any depth, because they could reach
+  `Object.prototype`. A write with one in its path or value throws `SettingsValidationError` with a `"Forbidden key"`
+  issue, and `get(path)` reads one as `undefined`. Stored ones are ignored as unknown keys.
+- Merging works the same on reads and in `update`: plain objects merge key by key; arrays, scalars and `null` replace.
+- In `update`, an `undefined` value leaves that Override as it was, and `null` is stored as a value, which passes only
+  if the schema allows it.
+- A value equal to the current default is still stored as an Override, so a later change of the default doesn't change
+  what the Owner chose. `reset(path)` is how an Owner follows the default again; with no Override at `path`, it
+  writes nothing.
+- A write whose Effective settings fail the schema throws `SettingsValidationError` and stores nothing. So does a
+  write with a key the schema doesn't know, which a schema that strips unknown keys would otherwise drop silently; the
+  issue for it has the message `"Unknown setting"`, as on read.
+- `getOverrides()` suits a settings page that marks which values are the Owner's own; it returns the document as
+  stored, including any Overrides a read would ignore.
+
+### Authorize the Owner first
+
+An Owner id is data, not a credential: the package stores and returns whatever Owner the app names, and checks
+nothing about who is asking. Before calling `scope(name, id)`, the app must decide that the current request may read
+or change that Owner's settings, for example by taking the user id from the session rather than from the request
+body, and by checking that the user is an admin before writing a `global` setting.
+
+### Deleting an Owner
+
+Settings aren't removed when the user or organization they belong to is deleted. Call `reset()` for that Owner as
+part of deleting it, so no Overrides are left behind.
+
+## Storing settings with Prisma
+
+`@rezwanul7/settings/prisma` exports `PrismaStore`, a Store over your own Prisma model. The package doesn't depend on
+`@prisma/client`; it takes the model delegate your generated client provides. Copy this model into your Prisma schema
+and create a migration:
+
+```prisma
+model Setting {
+  scope     String
+  ownerId   String
+  overrides Json
+  version   Int      @default(1)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@id([scope, ownerId])
+  @@map("settings")
+}
+```
+
+Each row holds one Owner's Overrides; an Owner with nothing stored has no row and reads the defaults. Keep the field
+names, the compound id on `scope` and `ownerId`, and the `version` default of `1`; the model and table names can be
+changed, as long as you pass the matching delegate.
+
+The row is removed by `reset()`, and a row created after it starts again at version 1. So a write that read the Owner
+just before a `reset()`, and stores after another write has recreated the row and brought it back to the version it
+read, overwrites that row: the Overrides written since the reset are lost. The model keeps no version once the row is
+gone, so the Store can't prevent that; call `reset()` when no other write to the Owner is expected, such as when
+deleting the Owner.
+
+```ts
+import { createSettings } from "@rezwanul7/settings";
+import { PrismaStore } from "@rezwanul7/settings/prisma";
+import { prisma } from "./db";
+import { global, user } from "./settings-definitions";
+
+export const settings = createSettings({
+  definitions: { user, global },
+  store: new PrismaStore({ delegate: prisma.setting }),
+});
+```
+
+## Next.js
+
+Create the settings once, in a server module, and wrap `get()` in React's `cache()` so a request that reads an
+Owner's settings in several Server Components reads the database once. Take the Owner id from the session, never from
+the client.
+
+```ts
+// src/server/settings.ts
+import "server-only";
+import { cache } from "react";
+import { createSettings } from "@rezwanul7/settings";
+import { PrismaStore } from "@rezwanul7/settings/prisma";
+import { auth } from "./auth";
+import { prisma } from "./db";
+import { global, user } from "./settings-definitions";
+
+export const settings = createSettings({
+  definitions: { user, global },
+  store: new PrismaStore({ delegate: prisma.setting }),
+  onInvalid: (owner, issues) => {
+    console.warn("Ignored stale settings", { owner, issues });
+  },
+});
+
+/** The signed-in user's Effective settings, read once per request. */
+export const getMySettings = cache(async () => {
+  const session = await auth();
+  if (!session) throw new Error("Not signed in");
+  return settings.scope("user", session.user.id).get();
+});
+
+/** The app-wide settings, read once per request. */
+export const getGlobalSettings = cache(() => settings.scope("global").get());
+```
+
+```ts
+// src/app/settings/actions.ts
+"use server";
+import { auth } from "@/server/auth";
+import { settings } from "@/server/settings";
+
+export async function setTheme(theme: "light" | "dark" | "system") {
+  const session = await auth();
+  if (!session) throw new Error("Not signed in");
+  await settings.scope("user", session.user.id).set("theme", theme);
+}
+```
+
+`cache()` lasts for one server request. A Server Action runs in its own request, so the page it revalidates reads the
+new value; code that writes and then reads in the same request should call `scope(...).get()` directly rather than the
+cached function.
+
+## Stale Overrides
+
+A schema change can make stored Overrides invalid, for example when an enum value is renamed or a field is removed.
+Such an Override is ignored rather than thrown, so the default applies at its path and one stale value doesn't break
+the Owner's page ([ADR-0001](./docs/adr/0001-overrides-only-ignored-when-invalid.md)):
+
+- On read, every Override at a path a validation issue names (or under it) is ignored, and so is every stored key the
+  schema no longer knows. Ignoring Overrides can reveal more issues, such as a refinement the validator skipped
+  while the shape had issues, so the settings are validated again until they pass or no issue names an Override left
+  to ignore. The rest of the Owner's Overrides still apply.
+- `onInvalid(owner, issues)` is called with the issues naming what was ignored; an unknown key is reported as an issue
+  with the message `"Unknown setting"`. Without `onInvalid`, they are ignored silently, so pass it to log them.
+- A read never changes the stored document. The next successful write for that Owner drops the ignored Overrides.
+- Writes read the Overrides first, so `onInvalid` can also be called during `set`, `update` or `reset(path)`, and more
+  than once for one write when it retries after a conflict.
+- If the Effective settings still fail the schema after the invalid Overrides are ignored, which means the defaults
+  themselves no longer fit, the read throws `SettingsDefinitionError`. A write still works from the Overrides it
+  can keep and validates only the result of its change, so a write that repairs the settings, such as setting the
+  value a refinement asks for, succeeds; one that doesn't throws `SettingsValidationError`.
+
+Changing a schema in a way that invalidates stored values is a product decision: those Owners go back to the default.
+
+## Concurrent writes
+
+Each write reads the Owner's Overrides and their version, applies its change and stores the result only if the version
+is unchanged. If another write got there first, it reads again and applies its change to the newer Overrides, so two
+requests changing different settings of one Owner both take effect. After `maxRetries` retries that all lost the race,
+it throws `SettingsConflictError`, whose `owner` names the Owner, and stores nothing; it is safe to try the whole write
+again later. `reset()` deletes without a version check. `MemoryStore` keeps an Owner's versions increasing across
+`reset()`, so a write that read the Owner before the reset is a conflict; `PrismaStore` can't, see
+[Storing settings with Prisma](#storing-settings-with-prisma).
+
+## Secret settings
+
+The package doesn't encrypt anything. Keep a secret setting, such as an SMTP password, sealed with
+[`@rezwanul7/secret-vault`](../secret-vault/README.md): seal it before `set()`, store the Sealed value as a string,
+and open it after `get()`. Give the Context the Owner, so a Sealed value copied to another Owner doesn't open.
+
+```ts
+import {
+  createSettings,
+  defineSettings,
+  type Owner,
+} from "@rezwanul7/settings";
+import { PrismaStore } from "@rezwanul7/settings/prisma";
+import { z } from "zod";
+import { prisma } from "./db";
+import { vault } from "./vault";
+
+const organization = defineSettings({
+  schema: z.object({
+    smtp: z.object({
+      host: z.string(),
+      // A Sealed value made by the Vault, never the password itself.
+      password: z.string().startsWith("vault:").nullable(),
+    }),
+  }),
+  defaults: { smtp: { host: "localhost", password: null } },
+});
+
+const settings = createSettings({
+  definitions: { organization },
+  store: new PrismaStore({ delegate: prisma.setting }),
+});
+
+function smtpPasswordContext(owner: Owner): string {
+  return `settings:smtp.password:${owner.scope}:${owner.id}`;
+}
+
+export async function saveSmtpPassword(orgId: string, password: string) {
+  const org = settings.scope("organization", orgId);
+  const sealed = await vault.encrypt(password, smtpPasswordContext(org.owner));
+  await org.set("smtp.password", sealed);
+}
+
+export async function readSmtpPassword(orgId: string): Promise<string | null> {
+  const org = settings.scope("organization", orgId);
+  const sealed = await org.get("smtp.password");
+  return sealed === null
+    ? null
+    : vault.decrypt(sealed, smtpPasswordContext(org.owner));
+}
+```
+
+The Effective settings then hold only the Sealed value, so they can be logged or passed around without exposing the
+secret; open it on the server, only where it is used.
+
+## Errors
+
+- `SettingsValidationError`: a write would make the Effective settings fail the schema. Nothing is stored. Its
+  `issues` are the Standard Schema issues, with paths into the settings, for showing next to form fields.
+- `SettingsConflictError`: a write lost the version race on every try, `maxRetries` retries included. Nothing is
+  stored, and the write can be tried again. Its `owner` names the Owner.
+- `SettingsDefinitionError`: a Scope name isn't in `definitions`, a Scope's defaults fail its schema, or an Owner's
+  Effective settings still fail it after ignoring stale Overrides. It is a bug in the app's Settings definitions, not
+  in the input, so don't show it to a user. It carries the `scope` and, for a failed validation, the `issues`.
+
+`createSettings` also throws a `RangeError` for an invalid `maxRetries`, and `scope()` throws a `TypeError` for an id
+passed to a single-owner Scope or missing for any other, which the types already rule out.
+
+```ts
+import { SettingsValidationError } from "@rezwanul7/settings";
+
+try {
+  await settings.scope("user", session.user.id).update(formValues);
+} catch (error) {
+  if (error instanceof SettingsValidationError) {
+    return { fieldErrors: error.issues };
+  }
+  throw error;
+}
+```
+
+## API reference
+
+Every export, parameter, and default is listed in the [API reference](./docs/api/README.md), generated from the source.
+
+## License
+
+MIT License. See [LICENSE](./LICENSE) for details.