@thomasfosterau/pulpit 0.0.0 → 0.1.0

package/dist/budgets.d.ts

@@ -0,0 +1,255 @@
+/**
+ * **Write budgets** (pulpit#199): a declared ceiling on how many writes of
+ * one kind an account may make in a rolling window, so a family that takes
+ * user content (comments, proposals, reports, posts) throttles it without
+ * every application re-adding the check.
+ *
+ * - **Declared once per family and action.** A {@link WriteBudget} names a
+ *   limit and a window; {@link bindBudget} binds it to a family's type, a
+ *   {@link BudgetCounter} and the access policy, and checks the declaration
+ *   (a malformed one throws {@link BudgetDeclarationError} when it is bound).
+ * - **Spent inside the write.** A chain write spends through
+ *   {@link budgetHook}, a before hook, so a write over budget appends
+ *   nothing; `./proposals`' `submit` and `./moderation`'s report `file` take
+ *   the bound budget as an opt-in and spend it before their insert. Either
+ *   way the refusal is `WriteRejected` with the reason {@link RATE_LIMITED},
+ *   which {@link isRateLimited} tells apart from every other refusal (the
+ *   wire's 429).
+ * - **Exempt above a rung.** An account the budget's `exempt` rung admits
+ *   (the moderate rung, by default) spends nothing.
+ * - **One counter seam.** The owner's decision on #199: count within the
+ *   write's transaction, with the seam shaped so an atomic counter can be
+ *   plugged in later. {@link countingCounter} is the counting
+ *   implementation, one indexed `count(*)` over the family's own rows; a
+ *   counter that holds its own state (a Durable Object, a locked row)
+ *   implements {@link BudgetCounter.take} directly.
+ *
+ * @copyright Thomas Foster
+ * @module pulpit/budgets
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { WriteRejected, type AccessPolicy, type BeforeWriteHook, type Viewer, type ViewerAccount } from "./subtype.ts";
+/**
+ * The `WriteRejected` reason a write over its budget carries, so the wire
+ * can answer 429 rather than 422.
+ *
+ * @since 0.1.0
+ */
+export declare const RATE_LIMITED = "rate-limited";
+/**
+ * Whether a refusal is a write budget's ({@link RATE_LIMITED}), not another
+ * hook's.
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import { isRateLimited, RATE_LIMITED } from "@thomasfosterau/pulpit/budgets";
+ * import { WriteRejected } from "@thomasfosterau/pulpit/subtype";
+ *
+ * const refusal = new WriteRejected({ type: "comments", id: "c-1", action: "create", reason: RATE_LIMITED });
+ * strictEqual(isRateLimited(refusal), true);
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare const isRateLimited: (error: WriteRejected) => boolean;
+/**
+ * A write budget: at most `limit` writes per account in any window of
+ * `windowSeconds`, for every account the `exempt` rung doesn't admit.
+ *
+ * @since 0.1.0
+ */
+export interface WriteBudget {
+    /** The most writes one account may make in a window: a positive safe integer. */
+    readonly limit: number;
+    /** The window's length, in seconds: a positive safe integer. */
+    readonly windowSeconds: number;
+    /**
+     * The rung that spends nothing, read from the access policy (as
+     * `./edges`' `rungGate` reads one). Absent, the moderate rung.
+     */
+    readonly exempt?: ((policy: AccessPolicy) => (account: ViewerAccount) => boolean) | undefined;
+}
+declare const BudgetDeclarationError_base: Schema.Class<BudgetDeclarationError, Schema.TaggedStruct<"BudgetDeclarationError", {
+    readonly type: Schema.String;
+    readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError & {
+    readonly brand: unique symbol;
+}>;
+/**
+ * A budget declaration that can never admit a write as intended (a limit or
+ * window that is not a positive safe integer), thrown by {@link bindBudget}
+ * when the budget is bound, never as an Effect failure.
+ *
+ * @since 0.1.0
+ */
+export declare class BudgetDeclarationError extends BudgetDeclarationError_base {
+}
+/**
+ * What a {@link BudgetCounter} is asked: whether the account may make one
+ * more write of `action` on the family `type`, given the window that
+ * started at `since` and the budget's `limit`.
+ *
+ * @since 0.1.0
+ */
+export interface BudgetRequest {
+    readonly type: string;
+    readonly action: string;
+    readonly accountId: string;
+    readonly since: Date;
+    readonly now: Date;
+    readonly limit: number;
+}
+/**
+ * The counter seam: spend one write against the budget, answering whether
+ * it was within it. Runs in the caller's transaction. A counting
+ * implementation ({@link countingCounter}) reads the writes already made,
+ * which the write itself then adds to; an atomic one (a Durable Object, a
+ * row taken `FOR UPDATE`) records the spend itself, and must spend nothing
+ * when it answers `false`. See the package README → Seams.
+ *
+ * @since 0.1.0
+ */
+export interface BudgetCounter<E, R> {
+    readonly take: (request: BudgetRequest) => Effect.Effect<boolean, E, R>;
+}
+/**
+ * The read {@link countingCounter} counts with: how many writes of `action`
+ * on `type` the account made at or after `since`, as one indexed
+ * `count(*)` over the family's own rows (`author_id`, `created_at`).
+ *
+ * @since 0.1.0
+ */
+export interface WriteCountStore<E, R> {
+    readonly countSince: (query: {
+        readonly type: string;
+        readonly action: string;
+        readonly accountId: string;
+        readonly since: Date;
+    }) => Effect.Effect<number, E, R>;
+}
+/**
+ * The count-within-the-transaction counter (gardeneria's
+ * `assertNotRateLimitedE`): a write is within budget while fewer than
+ * `limit` writes were made in the window. It spends nothing itself: the
+ * write's own row is the spend, and a write that rolls back took none.
+ * **It is exact but not atomic:** two concurrent transactions can both
+ * count `limit - 1` and both write. A family that must hold its limit under
+ * concurrency fills {@link BudgetCounter} with an atomic counter instead.
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import * as Effect from "effect/Effect";
+ * import { countingCounter } from "@thomasfosterau/pulpit/budgets";
+ *
+ * const counter = countingCounter({ countSince: () => Effect.succeed(2) });
+ * const request = {
+ *   type: "comments",
+ *   action: "create",
+ *   accountId: "u-1",
+ *   since: new Date(0),
+ *   now: new Date(60_000),
+ *   limit: 3,
+ * };
+ * strictEqual(Effect.runSync(counter.take(request)), true);
+ * strictEqual(Effect.runSync(counter.take({ ...request, limit: 2 })), false);
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare const countingCounter: <E, R>(store: WriteCountStore<E, R>) => BudgetCounter<E, R>;
+/**
+ * A budget bound to its family: {@link BoundBudget.spend} spends one write.
+ *
+ * @since 0.1.0
+ */
+export interface BoundBudget<E, R> {
+    readonly type: string;
+    readonly budget: WriteBudget;
+    /**
+     * Spend one write of `action` by `viewer` on the node `id`. An anonymous
+     * viewer spends nothing (the write's own gate refuses it), nor does one
+     * the exempt rung admits. Over budget it fails `WriteRejected` with
+     * {@link RATE_LIMITED}.
+     */
+    readonly spend: (viewer: Viewer, action: string, id: string) => Effect.Effect<void, WriteRejected | E, R>;
+}
+/**
+ * Bind a {@link WriteBudget} to a family's type, its counter and the access
+ * policy. Throws {@link BudgetDeclarationError} for a limit or window that
+ * is not a positive safe integer.
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import * as Effect from "effect/Effect";
+ * import * as Exit from "effect/Exit";
+ * import * as Option from "effect/Option";
+ * import { bindBudget } from "@thomasfosterau/pulpit/budgets";
+ * import { makeInMemoryBudgetCounter } from "@thomasfosterau/pulpit/testing";
+ *
+ * const policy = {
+ *   canViewPrivate: () => false,
+ *   canViewDeleted: () => false,
+ *   canModerate: () => false,
+ *   canWriteCorpus: () => false,
+ * };
+ * const comments = bindBudget({
+ *   type: "comments",
+ *   budget: { limit: 1, windowSeconds: 60 },
+ *   counter: makeInMemoryBudgetCounter(),
+ *   policy,
+ * });
+ * const member = Option.some({ id: "u-1", role: "member" });
+ * const twice = Effect.gen(function* () {
+ *   yield* comments.spend(member, "create", "c-1");
+ *   return yield* Effect.exit(comments.spend(member, "create", "c-2"));
+ * });
+ * strictEqual(Exit.isFailure(Effect.runSync(twice)), true);
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare const bindBudget: <E, R>(definition: {
+    readonly type: string;
+    readonly budget: WriteBudget;
+    readonly counter: BudgetCounter<E, R>;
+    readonly policy: AccessPolicy;
+}) => BoundBudget<E, R>;
+/**
+ * A bound budget as a before hook for a chain write (`./subtype`'s
+ * `hooks.before`), spending one write on each of the `actions` it lists
+ * (`create`, by default) and passing the patch through. A localised write
+ * spends once: the hook's `locales` pass spends nothing.
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import { bindBudget, budgetHook } from "@thomasfosterau/pulpit/budgets";
+ * import { makeInMemoryBudgetCounter } from "@thomasfosterau/pulpit/testing";
+ *
+ * const policy = {
+ *   canViewPrivate: () => false,
+ *   canViewDeleted: () => false,
+ *   canModerate: () => false,
+ *   canWriteCorpus: () => false,
+ * };
+ * const hook = budgetHook(
+ *   bindBudget({
+ *     type: "comments",
+ *     budget: { limit: 10, windowSeconds: 3600 },
+ *     counter: makeInMemoryBudgetCounter(),
+ *     policy,
+ *   }),
+ * );
+ * strictEqual(hook.name, "comments.budget");
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare const budgetHook: <E, R>(bound: BoundBudget<E, R>, actions?: ReadonlyArray<string>) => BeforeWriteHook<E, R>;
+export {};
+//# sourceMappingURL=budgets.d.ts.map

package/dist/budgets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budgets.d.ts","sourceRoot":"","sources":["../src/budgets.ts"],"names":[],"mappings":"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"}

package/dist/budgets.js

@@ -0,0 +1,211 @@
+/**
+ * **Write budgets** (pulpit#199): a declared ceiling on how many writes of
+ * one kind an account may make in a rolling window, so a family that takes
+ * user content (comments, proposals, reports, posts) throttles it without
+ * every application re-adding the check.
+ *
+ * - **Declared once per family and action.** A {@link WriteBudget} names a
+ *   limit and a window; {@link bindBudget} binds it to a family's type, a
+ *   {@link BudgetCounter} and the access policy, and checks the declaration
+ *   (a malformed one throws {@link BudgetDeclarationError} when it is bound).
+ * - **Spent inside the write.** A chain write spends through
+ *   {@link budgetHook}, a before hook, so a write over budget appends
+ *   nothing; `./proposals`' `submit` and `./moderation`'s report `file` take
+ *   the bound budget as an opt-in and spend it before their insert. Either
+ *   way the refusal is `WriteRejected` with the reason {@link RATE_LIMITED},
+ *   which {@link isRateLimited} tells apart from every other refusal (the
+ *   wire's 429).
+ * - **Exempt above a rung.** An account the budget's `exempt` rung admits
+ *   (the moderate rung, by default) spends nothing.
+ * - **One counter seam.** The owner's decision on #199: count within the
+ *   write's transaction, with the seam shaped so an atomic counter can be
+ *   plugged in later. {@link countingCounter} is the counting
+ *   implementation, one indexed `count(*)` over the family's own rows; a
+ *   counter that holds its own state (a Durable Object, a locked row)
+ *   implements {@link BudgetCounter.take} directly.
+ *
+ * @copyright Thomas Foster
+ * @module pulpit/budgets
+ * @since 0.1.0
+ */
+import * as Clock from "effect/Clock";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { WriteRejected, } from "./subtype.js";
+/**
+ * The `WriteRejected` reason a write over its budget carries, so the wire
+ * can answer 429 rather than 422.
+ *
+ * @since 0.1.0
+ */
+export const RATE_LIMITED = "rate-limited";
+/**
+ * Whether a refusal is a write budget's ({@link RATE_LIMITED}), not another
+ * hook's.
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import { isRateLimited, RATE_LIMITED } from "@thomasfosterau/pulpit/budgets";
+ * import { WriteRejected } from "@thomasfosterau/pulpit/subtype";
+ *
+ * const refusal = new WriteRejected({ type: "comments", id: "c-1", action: "create", reason: RATE_LIMITED });
+ * strictEqual(isRateLimited(refusal), true);
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const isRateLimited = (error) => error.reason === RATE_LIMITED;
+/**
+ * A budget declaration that can never admit a write as intended (a limit or
+ * window that is not a positive safe integer), thrown by {@link bindBudget}
+ * when the budget is bound, never as an Effect failure.
+ *
+ * @since 0.1.0
+ */
+export class BudgetDeclarationError extends Schema.TaggedError()("BudgetDeclarationError", { type: Schema.String, reason: Schema.String }) {
+}
+/**
+ * The count-within-the-transaction counter (gardeneria's
+ * `assertNotRateLimitedE`): a write is within budget while fewer than
+ * `limit` writes were made in the window. It spends nothing itself: the
+ * write's own row is the spend, and a write that rolls back took none.
+ * **It is exact but not atomic:** two concurrent transactions can both
+ * count `limit - 1` and both write. A family that must hold its limit under
+ * concurrency fills {@link BudgetCounter} with an atomic counter instead.
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import * as Effect from "effect/Effect";
+ * import { countingCounter } from "@thomasfosterau/pulpit/budgets";
+ *
+ * const counter = countingCounter({ countSince: () => Effect.succeed(2) });
+ * const request = {
+ *   type: "comments",
+ *   action: "create",
+ *   accountId: "u-1",
+ *   since: new Date(0),
+ *   now: new Date(60_000),
+ *   limit: 3,
+ * };
+ * strictEqual(Effect.runSync(counter.take(request)), true);
+ * strictEqual(Effect.runSync(counter.take({ ...request, limit: 2 })), false);
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const countingCounter = (store) => ({
+    take: (request) => Effect.map(store.countSince({
+        type: request.type,
+        action: request.action,
+        accountId: request.accountId,
+        since: request.since,
+    }), (count) => count < request.limit),
+});
+const positiveSafeInteger = (value) => Number.isSafeInteger(value) && value > 0;
+/**
+ * Bind a {@link WriteBudget} to a family's type, its counter and the access
+ * policy. Throws {@link BudgetDeclarationError} for a limit or window that
+ * is not a positive safe integer.
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import * as Effect from "effect/Effect";
+ * import * as Exit from "effect/Exit";
+ * import * as Option from "effect/Option";
+ * import { bindBudget } from "@thomasfosterau/pulpit/budgets";
+ * import { makeInMemoryBudgetCounter } from "@thomasfosterau/pulpit/testing";
+ *
+ * const policy = {
+ *   canViewPrivate: () => false,
+ *   canViewDeleted: () => false,
+ *   canModerate: () => false,
+ *   canWriteCorpus: () => false,
+ * };
+ * const comments = bindBudget({
+ *   type: "comments",
+ *   budget: { limit: 1, windowSeconds: 60 },
+ *   counter: makeInMemoryBudgetCounter(),
+ *   policy,
+ * });
+ * const member = Option.some({ id: "u-1", role: "member" });
+ * const twice = Effect.gen(function* () {
+ *   yield* comments.spend(member, "create", "c-1");
+ *   return yield* Effect.exit(comments.spend(member, "create", "c-2"));
+ * });
+ * strictEqual(Exit.isFailure(Effect.runSync(twice)), true);
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const bindBudget = (definition) => {
+    const { type, budget, counter, policy } = definition;
+    if (!positiveSafeInteger(budget.limit)) {
+        throw new BudgetDeclarationError({ type, reason: "limit must be a positive safe integer" });
+    }
+    if (!positiveSafeInteger(budget.windowSeconds)) {
+        throw new BudgetDeclarationError({
+            type,
+            reason: "windowSeconds must be a positive safe integer",
+        });
+    }
+    const exempt = (budget.exempt ?? ((rungs) => rungs.canModerate))(policy);
+    const windowMillis = budget.windowSeconds * 1000;
+    const spend = (viewer, action, id) => Option.match(Option.filter(viewer, (account) => !exempt(account)), {
+        onNone: () => Effect.void,
+        onSome: (account) => Effect.flatMap(Clock.currentTimeMillis, (millis) => Effect.flatMap(counter.take({
+            type,
+            action,
+            accountId: account.id,
+            since: DateTime.toDate(DateTime.makeUnsafe(millis - windowMillis)),
+            now: DateTime.toDate(DateTime.makeUnsafe(millis)),
+            limit: budget.limit,
+        }), (within) => within
+            ? Effect.void
+            : Effect.fail(new WriteRejected({ type, id, action, reason: RATE_LIMITED })))),
+    });
+    return { type, budget, spend };
+};
+/**
+ * A bound budget as a before hook for a chain write (`./subtype`'s
+ * `hooks.before`), spending one write on each of the `actions` it lists
+ * (`create`, by default) and passing the patch through. A localised write
+ * spends once: the hook's `locales` pass spends nothing.
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import { bindBudget, budgetHook } from "@thomasfosterau/pulpit/budgets";
+ * import { makeInMemoryBudgetCounter } from "@thomasfosterau/pulpit/testing";
+ *
+ * const policy = {
+ *   canViewPrivate: () => false,
+ *   canViewDeleted: () => false,
+ *   canModerate: () => false,
+ *   canWriteCorpus: () => false,
+ * };
+ * const hook = budgetHook(
+ *   bindBudget({
+ *     type: "comments",
+ *     budget: { limit: 10, windowSeconds: 3600 },
+ *     counter: makeInMemoryBudgetCounter(),
+ *     policy,
+ *   }),
+ * );
+ * strictEqual(hook.name, "comments.budget");
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const budgetHook = (bound, actions = ["create"]) => ({
+    name: `${bound.type}.budget`,
+    run: (event) => actions.includes(event.action)
+        ? Effect.as(bound.spend(event.viewer, event.action, event.id), event.patch)
+        : Effect.succeed(event.patch),
+    locales: (event) => Effect.succeed(event.locales ?? {}),
+});
+//# sourceMappingURL=budgets.js.map

package/dist/budgets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budgets.js","sourceRoot":"","sources":["../src/budgets.ts"],"names":[],"mappings":"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"}

package/dist/cache.d.ts

@@ -0,0 +1,154 @@
+/**
+ * **The reference resource cache** (pulpit#205) — `./subtype`'s
+ * {@link ResourceCacheSeam}, with a read-through `get`, over a minimal
+ * versioned key-value seam ({@link VersionedKv}).
+ *
+ * The behavioural spec is the four apps' own caches (website's, gardeneria's,
+ * preferenceflow's and in-the-dark's `apps/api/src/cache.ts`), which this
+ * replaces: one implementation of the contract the kernel already states.
+ *
+ * - **Compare-on-set** (pulpit#121). Every entry carries the version it
+ *   speaks for, and the KV seam's one conditional write keeps the highest:
+ *   a `set` or `delete` below the stored version changes nothing, and an
+ *   eviction raises the version, so a racing writer's late write-through can
+ *   never re-cache a resource older than one already replaced or evicted.
+ * - **An eviction wins a tie.** A tombstone outranks a value at the same
+ *   version: only a strictly newer write clears it, so a read-through that
+ *   loaded the row before an unpublish at that version can't re-cache it.
+ *   The cache stores a rank, `2·version` for a value and `2·version + 1` for
+ *   a tombstone, as the entry's `version`, so the seam still compares one
+ *   number.
+ * - **Tombstones outlive values.** A tombstone is kept for
+ *   `tombstoneTtlSeconds` (by default a day, and never less than the value
+ *   TTL), which must exceed the longest a write can be in flight: a late
+ *   write-through that arrives after its tombstone has expired is no longer
+ *   ordered against it.
+ * - **Serveability on both sides** (`CACHE-AUTH-005`). `set` refuses (and
+ *   evicts) a resource the `serveable` policy refuses, and `get` checks it
+ *   again, so a policy change can't serve a stale cached private row.
+ * - **Decode or evict.** `get` decodes the stored value with the resource's
+ *   schema; a value that no longer decodes (the schema moved) is evicted and
+ *   read as a miss.
+ * - **A TTL backstop.** Every write carries the configured TTL, so an entry
+ *   no write ever evicted still expires.
+ * - **Never fails.** A KV failure reads as a miss and skips a write: the
+ *   cache is an optimisation, and the store stays the source of truth.
+ *
+ * The KV seam is the application's (a Durable Object, Redis, a SQL table):
+ * nothing here imports a platform. Workers KV alone has no conditional
+ * write, so it can't fill {@link VersionedKv.putIfNotBehind}.
+ *
+ * @copyright Thomas Foster
+ * @module pulpit/cache
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import type { ResourceCacheSeam } from "./subtype.ts";
+/**
+ * One stored entry: the rank it is ordered by, and the encoded resource, or
+ * none for an eviction (a tombstone that keeps the rank). `makeResourceCache`
+ * stores `2·version` for a value and `2·version + 1` for a tombstone, so a
+ * tombstone outranks a value at the same node version.
+ *
+ * @since 0.1.0
+ */
+export interface KvEntry {
+    readonly version: bigint;
+    readonly value: Option.Option<Schema.Json>;
+}
+/**
+ * The minimal versioned key-value store an application supplies. A store
+ * seam: no policy, fails only with its `E`. See the package README → Seams.
+ *
+ * @since 0.1.0
+ */
+export interface VersionedKv<E, R> {
+    /** The entry at `key`, or none (never written, or expired). */
+    readonly get: (key: string) => Effect.Effect<Option.Option<KvEntry>, E, R>;
+    /**
+     * Write `entry` at `key` with a TTL of `ttlSeconds`, **in one atomic
+     * step**, unless the stored entry's version is above `entry.version`;
+     * whether it wrote. A store with no conditional write cannot fill this
+     * seam.
+     */
+    readonly putIfNotBehind: (key: string, entry: KvEntry, ttlSeconds: number) => Effect.Effect<boolean, E, R>;
+}
+/**
+ * {@link makeResourceCache}'s configuration.
+ *
+ * @since 0.1.0
+ */
+export interface ResourceCacheOptions<Resource, E, R> {
+    readonly kv: VersionedKv<E, R>;
+    /** The resource's schema: its JSON encoding in the store, decoded on every read. */
+    readonly schema: Schema.Codec<Resource, Schema.Json>;
+    /** The `CACHE-AUTH-005` serveability policy (typically `./publication`'s `serveablePolicy`). */
+    readonly serveable: (resource: Resource) => boolean;
+    /** The key prefix, typically the leaf's type and a schema generation (`posts:v3:`). */
+    readonly prefix: string;
+    /** The TTL backstop every value write carries, in seconds (clamped to at least 1). */
+    readonly ttlSeconds: number;
+    /**
+     * How long an eviction's tombstone is kept, in seconds: it must exceed the
+     * longest a write-through or read-through fill can be in flight, since a
+     * stale write that lands after its tombstone expired is no longer refused.
+     * Defaults to a day ({@link DEFAULT_TOMBSTONE_TTL_SECONDS}), and is never
+     * less than `ttlSeconds`.
+     */
+    readonly tombstoneTtlSeconds?: number | undefined;
+}
+/**
+ * The default time an eviction's tombstone is kept: one day, far longer than
+ * any request can be in flight.
+ *
+ * @since 0.1.0
+ */
+export declare const DEFAULT_TOMBSTONE_TTL_SECONDS = 86400;
+/**
+ * A resource cache: the kernel's write-through seam plus the read-through
+ * `get`.
+ *
+ * @since 0.1.0
+ */
+export interface ResourceCache<Resource, R> extends ResourceCacheSeam<Resource, R> {
+    /**
+     * The cached resource for `id`: none on a miss, an eviction, a value that
+     * no longer decodes (evicted at its version) or one the policy no longer
+     * serves (evicted likewise). Never fails.
+     */
+    readonly get: (id: string) => Effect.Effect<Option.Option<Resource>, never, R>;
+}
+/**
+ * The reference {@link ResourceCacheSeam} over a {@link VersionedKv}.
+ *
+ * @example
+ * ```ts
+ * import { deepStrictEqual } from "node:assert";
+ * import * as Effect from "effect/Effect";
+ * import * as Option from "effect/Option";
+ * import * as Schema from "effect/Schema";
+ * import { makeResourceCache } from "@thomasfosterau/pulpit/cache";
+ * import { makeInMemoryVersionedKv } from "@thomasfosterau/pulpit/testing";
+ *
+ * const Post = Schema.Struct({ id: Schema.String, visibility: Schema.String });
+ * const cache = makeResourceCache({
+ *   kv: makeInMemoryVersionedKv(),
+ *   schema: Post,
+ *   serveable: (post) => post.visibility === "public",
+ *   prefix: "posts:v1:",
+ *   ttlSeconds: 3600,
+ * });
+ * const program = Effect.gen(function* () {
+ *   yield* cache.set("p-1", { id: "p-1", visibility: "public" }, 1n);
+ *   yield* cache.set("p-1", { id: "p-1", visibility: "private" }, 0n); // behind: no-op
+ *   return yield* cache.get("p-1");
+ * });
+ * deepStrictEqual(Effect.runSync(program), Option.some({ id: "p-1", visibility: "public" }));
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare const makeResourceCache: <Resource, E, R>(options: ResourceCacheOptions<Resource, E, R>) => ResourceCache<Resource, R>;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAItD;;;;;;;GAOG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;CAC5C;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,EAAE,CAAC;IAC/B,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3E;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,EAAE,CACvB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,MAAM,KACf,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CACnC;AAID;;;;GAIG;AACH,MAAM,WAAW,oBAAoB,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC;IAClD,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/B,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IACrD,gGAAgG;IAChG,QAAQ,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,OAAO,CAAC;IACpD,uFAAuF;IACvF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sFAAsF;IACtF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;;;OAMG;IAEH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnD;AAED;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,QAAS,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,WAAW,aAAa,CAAC,QAAQ,EAAE,CAAC,CAAE,SAAQ,iBAAiB,CAAC,QAAQ,EAAE,CAAC,CAAC;IAChF;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;CAChF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ,EAAE,CAAC,EAAE,CAAC,WACrC,oBAAoB,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,KAC5C,aAAa,CAAC,QAAQ,EAAE,CAAC,CA+C3B,CAAC"}