@rezwanul7/settings 0.0.0-stage → 0.1.0

package/dist/prisma.d.ts

@@ -0,0 +1,148 @@
+import { S as SettingsStore, O as Owner, a as StoredOverrides } from './store-B4pWek75.js';
+
+/**
+ * @rezwanul7/settings/prisma: a Store over the app's own Prisma model delegate, such as `prisma.setting`. The package
+ * doesn't depend on `@prisma/client`; {@link PrismaSettingsDelegate} describes the methods the Store calls, and the
+ * delegate Prisma generates for the model below fits it.
+ *
+ * ```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")
+ * }
+ * ```
+ *
+ * @module prisma
+ */
+
+/** A JSON value as Prisma accepts it for a `Json` field. */
+type JsonInput = string | number | boolean | null | {
+    readonly [key: string]: JsonInput;
+} | readonly JsonInput[];
+/**
+ * The methods of a Prisma model delegate that {@link PrismaStore} calls, typed by their shape so the package needn't
+ * depend on `@prisma/client`. Pass the delegate Prisma generates for the Setting model, such as `prisma.setting`.
+ */
+interface PrismaSettingsDelegate {
+    /**
+     * Reads one row by the `scope_ownerId` compound key.
+     *
+     * @param args - The compound key to find.
+     * @returns The row, or `null` when there is none.
+     */
+    findUnique(args: {
+        where: {
+            scope_ownerId: {
+                scope: string;
+                ownerId: string;
+            };
+        };
+    }): PromiseLike<{
+        /** The `overrides` column. */
+        overrides: unknown;
+        /** The `version` column. */
+        version: number;
+    } | null>;
+    /**
+     * Creates a row, rejecting with an error whose `code` is `P2002` when one exists for the key.
+     *
+     * @param args - The new row's key and Overrides; its version comes from the column default.
+     * @returns The created row.
+     */
+    create(args: {
+        data: {
+            scope: string;
+            ownerId: string;
+            overrides: {
+                readonly [key: string]: JsonInput;
+            };
+        };
+    }): PromiseLike<{
+        /** The `version` column, set by its default. */
+        version: number;
+    }>;
+    /**
+     * Updates the rows matching a filter.
+     *
+     * @param args - The row's key and the version it must be at, and the new Overrides with the version increment.
+     * @returns How many rows were updated.
+     */
+    updateMany(args: {
+        where: {
+            scope: string;
+            ownerId: string;
+            version: number;
+        };
+        data: {
+            overrides: {
+                readonly [key: string]: JsonInput;
+            };
+            version: {
+                increment: number;
+            };
+        };
+    }): PromiseLike<{
+        /** How many rows matched. */
+        count: number;
+    }>;
+    /**
+     * Deletes the rows matching a filter; matching none is not an error.
+     *
+     * @param args - The row's key.
+     * @returns How many rows were deleted.
+     */
+    deleteMany(args: {
+        where: {
+            scope: string;
+            ownerId: string;
+        };
+    }): PromiseLike<{
+        /** How many rows matched. */
+        count: number;
+    }>;
+}
+/**
+ * A Store that keeps each Owner's Overrides as one row of the app's Prisma model, guarded by its `version` column.
+ * An update only matches the row at the version the caller read, and a create that finds the row already there is a
+ * conflict, so the retries of the settings created by `createSettings` work against a real database.
+ *
+ * Known limitation: `delete` removes the row, and a row created after it starts again at the column default of `1`,
+ * so versions can repeat across a delete. A write that read version `n` of the old row before `reset()`, and stores
+ * after other writes have recreated the row and brought it back to version `n`, overwrites the new row: the Overrides
+ * written since the reset are lost and the old ones, with that write's change, come back. It takes a `reset()` and
+ * another write to the same Owner both landing while that write is running. Avoiding it would need the version to
+ * outlive the row, which the model doesn't keep, so call `reset()` when no other write to the Owner is expected, such
+ * as when deleting the Owner.
+ *
+ * @example
+ * import { PrismaStore } from "@rezwanul7/settings/prisma";
+ *
+ * const settings = createSettings({
+ *   definitions: { user },
+ *   store: new PrismaStore({ delegate: prisma.setting }),
+ * });
+ */
+declare class PrismaStore implements SettingsStore {
+    #private;
+    /**
+     * @param options - Takes `delegate`: the app's Prisma model delegate, such as `prisma.setting`.
+     */
+    constructor(options: {
+        delegate: PrismaSettingsDelegate;
+    });
+    /** {@inheritDoc @rezwanul7/settings!SettingsStore.read} */
+    read(owner: Owner): Promise<StoredOverrides | null>;
+    /** {@inheritDoc @rezwanul7/settings!SettingsStore.write} */
+    write(owner: Owner, overrides: Record<string, unknown>, expectedVersion: number | null): Promise<number | null>;
+    /** {@inheritDoc @rezwanul7/settings!SettingsStore.delete} */
+    delete(owner: Owner): Promise<void>;
+}
+
+export { type PrismaSettingsDelegate, PrismaStore };

package/dist/prisma.js

@@ -0,0 +1,53 @@
+// src/prisma.ts
+var PrismaStore = class {
+  #delegate;
+  /**
+   * @param options - Takes `delegate`: the app's Prisma model delegate, such as `prisma.setting`.
+   */
+  constructor(options) {
+    this.#delegate = options.delegate;
+  }
+  /** {@inheritDoc @rezwanul7/settings!SettingsStore.read} */
+  async read(owner) {
+    const row = await this.#delegate.findUnique({
+      where: { scope_ownerId: key(owner) }
+    });
+    if (row === null) return null;
+    return {
+      overrides: row.overrides,
+      version: row.version
+    };
+  }
+  /** {@inheritDoc @rezwanul7/settings!SettingsStore.write} */
+  async write(owner, overrides, expectedVersion) {
+    const json = overrides;
+    if (expectedVersion === null) {
+      try {
+        const row = await this.#delegate.create({
+          data: { ...key(owner), overrides: json }
+        });
+        return row.version;
+      } catch (error) {
+        if (isUniqueConstraintError(error)) return null;
+        throw error;
+      }
+    }
+    const { count } = await this.#delegate.updateMany({
+      where: { ...key(owner), version: expectedVersion },
+      data: { overrides: json, version: { increment: 1 } }
+    });
+    return count === 0 ? null : expectedVersion + 1;
+  }
+  /** {@inheritDoc @rezwanul7/settings!SettingsStore.delete} */
+  async delete(owner) {
+    await this.#delegate.deleteMany({ where: key(owner) });
+  }
+};
+function key(owner) {
+  return { scope: owner.scope, ownerId: owner.id };
+}
+function isUniqueConstraintError(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "P2002";
+}
+
+export { PrismaStore };

package/dist/store-B4pWek75.d.cts

@@ -0,0 +1,61 @@
+/**
+ * One Scope plus an id, such as user `1`: the thing a set of Overrides belongs to. The Owner of a single-owner Scope
+ * has the id `"default"`.
+ */
+interface Owner {
+    /** The Scope name, such as `"user"` or `"global"`. */
+    readonly scope: string;
+    /** The Owner's id within its Scope. */
+    readonly id: string;
+}
+/** An Owner's Overrides as a Store keeps them, with the version a write must name to replace them. */
+interface StoredOverrides {
+    /**
+     * Everything stored for the Owner, as one JSON object. Defaults are never part of it. Every value in it must be a
+     * JSON value: a string, finite number, boolean, `null`, array or plain object.
+     */
+    readonly overrides: Record<string, unknown>;
+    /**
+     * Increases on every successful write; a write that names an older version is a conflict. A Store should never
+     * give an Owner a version it had before, even after {@link SettingsStore.delete}, or a write that read the old
+     * document could overwrite the new one.
+     */
+    readonly version: number;
+}
+/**
+ * Where Overrides are kept, such as a database table or process memory. A Store keeps one document per Owner and
+ * guards writes with a version. It reports a conflict by returning `null` from {@link SettingsStore.write}; it never
+ * throws for a conflict and never retries, because retrying is the job of the settings created by `createSettings`.
+ *
+ * A Store keeps Overrides as JSON: what it reads back equals `JSON.parse(JSON.stringify(overrides))` of what was
+ * written, so a `Date` reads back as its ISO string and an `undefined` value is dropped. Overrides must therefore be
+ * JSON values; for a date, store its string and convert it where the setting is used.
+ */
+interface SettingsStore {
+    /**
+     * Reads an Owner's Overrides.
+     *
+     * @param owner - The Owner to read.
+     * @returns The Overrides and their version, or `null` when nothing is stored for the Owner.
+     */
+    read(owner: Owner): Promise<StoredOverrides | null>;
+    /**
+     * Replaces an Owner's Overrides if they are still at `expectedVersion`.
+     *
+     * @param owner - The Owner to write.
+     * @param overrides - The Owner's complete new Overrides.
+     * @param expectedVersion - The version the caller read, or `null` to create the document for an Owner with nothing
+     *   stored.
+     * @returns The new version, or `null` on a conflict: the stored version isn't `expectedVersion`, or a create found
+     *   a document already there.
+     */
+    write(owner: Owner, overrides: Record<string, unknown>, expectedVersion: number | null): Promise<number | null>;
+    /**
+     * Deletes everything stored for an Owner. Deleting an Owner with nothing stored does nothing.
+     *
+     * @param owner - The Owner to delete.
+     */
+    delete(owner: Owner): Promise<void>;
+}
+
+export type { Owner as O, SettingsStore as S, StoredOverrides as a };

package/dist/store-B4pWek75.d.ts

@@ -0,0 +1,61 @@
+/**
+ * One Scope plus an id, such as user `1`: the thing a set of Overrides belongs to. The Owner of a single-owner Scope
+ * has the id `"default"`.
+ */
+interface Owner {
+    /** The Scope name, such as `"user"` or `"global"`. */
+    readonly scope: string;
+    /** The Owner's id within its Scope. */
+    readonly id: string;
+}
+/** An Owner's Overrides as a Store keeps them, with the version a write must name to replace them. */
+interface StoredOverrides {
+    /**
+     * Everything stored for the Owner, as one JSON object. Defaults are never part of it. Every value in it must be a
+     * JSON value: a string, finite number, boolean, `null`, array or plain object.
+     */
+    readonly overrides: Record<string, unknown>;
+    /**
+     * Increases on every successful write; a write that names an older version is a conflict. A Store should never
+     * give an Owner a version it had before, even after {@link SettingsStore.delete}, or a write that read the old
+     * document could overwrite the new one.
+     */
+    readonly version: number;
+}
+/**
+ * Where Overrides are kept, such as a database table or process memory. A Store keeps one document per Owner and
+ * guards writes with a version. It reports a conflict by returning `null` from {@link SettingsStore.write}; it never
+ * throws for a conflict and never retries, because retrying is the job of the settings created by `createSettings`.
+ *
+ * A Store keeps Overrides as JSON: what it reads back equals `JSON.parse(JSON.stringify(overrides))` of what was
+ * written, so a `Date` reads back as its ISO string and an `undefined` value is dropped. Overrides must therefore be
+ * JSON values; for a date, store its string and convert it where the setting is used.
+ */
+interface SettingsStore {
+    /**
+     * Reads an Owner's Overrides.
+     *
+     * @param owner - The Owner to read.
+     * @returns The Overrides and their version, or `null` when nothing is stored for the Owner.
+     */
+    read(owner: Owner): Promise<StoredOverrides | null>;
+    /**
+     * Replaces an Owner's Overrides if they are still at `expectedVersion`.
+     *
+     * @param owner - The Owner to write.
+     * @param overrides - The Owner's complete new Overrides.
+     * @param expectedVersion - The version the caller read, or `null` to create the document for an Owner with nothing
+     *   stored.
+     * @returns The new version, or `null` on a conflict: the stored version isn't `expectedVersion`, or a create found
+     *   a document already there.
+     */
+    write(owner: Owner, overrides: Record<string, unknown>, expectedVersion: number | null): Promise<number | null>;
+    /**
+     * Deletes everything stored for an Owner. Deleting an Owner with nothing stored does nothing.
+     *
+     * @param owner - The Owner to delete.
+     */
+    delete(owner: Owner): Promise<void>;
+}
+
+export type { Owner as O, SettingsStore as S, StoredOverrides as a };

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@rezwanul7/settings",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rezwanul7/turbopack-package-development.git",
+    "directory": "packages/settings"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./prisma": {
+      "import": {
+        "types": "./dist/prisma.d.ts",
+        "default": "./dist/prisma.js"
+      },
+      "require": {
+        "types": "./dist/prisma.d.cts",
+        "default": "./dist/prisma.cjs"
+      }
+    }
+  },
+  "devDependencies": {
+    "@repo/eslint-config": "0.0.0",
+    "@repo/typescript-config": "0.0.0",
+    "@types/node": "^22.15.3",
+    "@vitest/coverage-v8": "4.0.18",
+    "esbuild": "0.27.3",
+    "eslint": "^9.39.1",
+    "tsup": "^8.5.1",
+    "typedoc-plugin-markdown": "4.14.0",
+    "vitest": "^4.0.18",
+    "zod": "^4.6.7"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "check-types": "tsc --noEmit",
+    "check-docs": "typedoc --readme none --disableSources",
+    "check-package": "publint && attw --pack . --profile node16",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
 }