@astilba/cache 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,131 @@
+import { $ as Clock, A as Tier, B as EnvelopeEnc, C as L3Ineligibility, Ct as TelemetrySink, D as RenderCollector, Dt as Watermark, E as PurgeResult, Et as Validity, F as compound, G as Bus, H as Duration, I as globalTag, J as CasOrder, K as BusEvent, L as t, M as createCache, N as Tag, O as RequestContext, P as TagPart, Q as CdnMode, R as ChannelState, S as L3Emission, St as TelemetryEventName, T as OriginLoadGuard, Tt as TagKnowledge, U as DurationUnit, V as EnvelopeKind, W as duration, X as CasStore, Y as CasRecord, Z as Cdn, _ as GetOptions, _t as SinkErrorHook, a as DeleteSelector, at as Registry, b as GracedInfo, bt as TelemetryConfig, c as ExplainDependencyScope, ct as Store, d as ExplainScope, dt as StoreWriteError, et as Codec, f as ExplainTtl, ft as StoreWriteOptions, g as FactoryCtx, gt as memory, h as Explanation, ht as isStoreWriteError, i as CacheEntry, it as ReadKind, j as UnknownPolicy, k as Scope, l as ExplainIdentity, lt as StoreMetadata, m as ExplainedDependency, mt as TagChange, n as CacheConfig, nt as LockHandle, o as EntryFactoryCtx, ot as RegistryAck, p as ExplainVerdict, pt as Subscription, q as BusFrame, r as CacheDefaults, rt as MemoryOptions, s as ExpireSelector, st as Rng, t as Cache, tt as Lock, u as ExplainReaderState, ut as StoreValue, v as GetOrSetEntryOptions, vt as StrongDegradedReason, w as MatchedHint, wt as Consistency, x as L3Budget, xt as TelemetryEvent, y as GetOrSetOptions, yt as TELEMETRY_EVENTS, z as Envelope } from "./cache-YWn0VZpn.js";
+//#region src/errors.d.ts
+/**
+ * Thrown by every public entry point during the correctness-kernel phase. A RED
+ * invariant that fails with `NotImplementedError` is red for the right reason
+ * (the kernel is unimplemented), as opposed to a toolchain/config failure.
+ */
+declare class NotImplementedError extends Error {
+  constructor(symbol: string);
+}
+/** Whether a cache timeout originated inside the cache or from a caller abort. */
+type CacheTimeoutSource = "cache" | "caller";
+/**
+ * Distinguishes cache-originated timeouts (retriable — evidence about origin
+ * health) from caller aborts (not evidence of origin health).
+ */
+declare class CacheTimeoutError extends Error {
+  readonly source: CacheTimeoutSource;
+  constructor(source: CacheTimeoutSource, message?: string);
+}
+/**
+ * Thrown by a `strong` read when the registry is unreachable. Opt out with
+ * `onUnavailable: 'eventual'`.
+ */
+declare class RegistryUnavailableError extends Error {
+  /**
+   * `options.cause` carries the error this one displaced, where there was one. The serve-time
+   * re-validation of a graced candidate runs INSIDE a failed fill: if the registry is unreachable
+   * there, this error is what the caller sees instead of the factory failure that started it, so
+   * the factory failure rides along rather than being dropped. Nothing is lost and callers get one
+   * uniform type. Widened additively — `new RegistryUnavailableError(msg)` is unchanged.
+   */
+  constructor(message?: string, options?: ErrorOptions);
+}
+/**
+ * Thrown by a read whose tag knowledge is UNKNOWN under `unknownPolicy: 'error'`.
+ *
+ * WHAT MAKES THIS DISTINCT FROM A MISS, AND WHY THE DISTINCTION IS THE POINT. Every other
+ * fail-closed resolution refills from origin, which is hard-safe exactly when the origin is truth.
+ * `'error'` is the policy for the case where it is NOT: a namespace under a takedown or a legal
+ * embargo. There, an origin that has not caught up yet can lose a race with the purge and hand back
+ * exactly the content that was supposed to vanish. So this policy declines to guess: it neither
+ * serves the unknown value nor replaces it
+ * with a fresh one, and the caller — who knows what the content is — decides. A policy that resolved
+ * to the same refill as `'miss'` would be a switch that reads as protection and does nothing, which
+ * is worse than no switch at all.
+ *
+ * Carries the key and the tags whose knowledge was unknown, so a caller can tell an embargoed
+ * dependency from a cold one. EXACTLY those: the tags this read could not establish, and no others.
+ * A payload of everything the entry declared cannot answer the question the field exists for — the
+ * caller would have to guess which of them was the problem, which is the guess this policy refuses
+ * to make on their behalf. Reserved (`__`-prefixed) tags never appear here: they are the kernel's
+ * own bookkeeping, they are unknown for exactly the same reason the user's are, and naming them
+ * tells the caller nothing they can act on.
+ */
+declare class UnknownTagError extends Error {
+  readonly key: string;
+  readonly tags: readonly string[];
+  /**
+   * `armedBy` names what selected this resolution — an explicit `unknownPolicy: 'error'`, or the
+   * `takedownSensitive` override that outranks it. The message used to state the former
+   * unconditionally, which was wrong precisely on the takedown path: the one place where the
+   * operator most needs to know which switch fired is the one where the message named the other.
+   */
+  constructor(key: string, tags: readonly string[], armedBy?: "unknownPolicy" | "takedownSensitive");
+}
+/** A typed HTTP error carrying the offending status and response. */
+declare class HttpError extends Error {
+  readonly status: number;
+  readonly response: Response;
+  constructor(response: Response);
+}
+/**
+ * Thrown at the `getOrSet`/`getOrSetEntry` write boundary when a caller-supplied
+ * tag is malformed — in particular a user tag beginning with the reserved `__`
+ * prefix. A real runtime error, never `NotImplementedError`: tag
+ * validation is not deferred kernel logic.
+ */
+declare class InvalidTagError extends Error {
+  readonly tag: string;
+  constructor(tag: string, reason: string);
+}
+/**
+ * Thrown by `duration()` when a computed duration is malformed — a non-positive or
+ * non-finite `value`, or (critical case) a `value × unitFactor` product that
+ * is not a finite, positive, safe integer once multiplied out. A real
+ * runtime error, never `NotImplementedError`: duration validation is not deferred kernel
+ * logic. Mirrors `InvalidTagError` — the builder rejects a bad input, it never coerces one.
+ */
+declare class InvalidDurationError extends Error {
+  readonly value: number;
+  readonly unit: string;
+  constructor(value: number, unit: string, reason: string);
+}
+/**
+ * Thrown by the plain `getOrSet` form when a fill is fenced past its write-back
+ * retry attempt budget: a hard delete keeps landing mid-fill/mid-
+ * refresh so the accepted result never postdates every purge visible at
+ * write-back, and the fill fails within its attempt budget rather than ever
+ * storing or serving a fenced value. A real runtime outcome, never
+ * `NotImplementedError` — the entry form (`getOrSetEntry`) surfaces the same
+ * outcome as `{ value: undefined }` instead of throwing.
+ */
+declare class FencedError extends Error {
+  readonly key: string;
+  constructor(key: string, message?: string);
+}
+/**
+ * Thrown when a factory declares a dependency after it has settled: a
+ * `ctx.dependsOn`/`ctx.setTags` call reaching the context AFTER the factory promise
+ * resolved or rejected. The fill's tag set closes at settle, so a later declaration is
+ * outside the value's lifetime and cannot join it. A real runtime error, never
+ * `NotImplementedError`. Carries the offending key.
+ */
+declare class FactorySettledError extends Error {
+  readonly key: string;
+  constructor(key: string);
+}
+//#endregion
+//#region src/http.d.ts
+/** Wrap a non-ok `Response` into a typed `HttpError`. */
+declare function httpError(response: Response): HttpError;
+/**
+ * The default `staleIfError` predicate — retriable: the default
+ * retriable set, network errors, and cache-originated timeouts. `404/410/403` are
+ * facts, never masked (never retriable) — a caller-abort `CacheTimeoutError` with
+ * `source:'caller'` is likewise not evidence of origin health.
+ */
+declare function isRetriableHttp(err: unknown): boolean;
+//#endregion
+export { type Bus, type BusEvent, type BusFrame, type Cache, type CacheConfig, type CacheDefaults, type CacheEntry, CacheTimeoutError, type CacheTimeoutSource, type CasOrder, type CasRecord, type CasStore, type Cdn, type CdnMode, type ChannelState, type Clock, type Codec, type Consistency, type DeleteSelector, type Duration, type DurationUnit, type EntryFactoryCtx, type Envelope, type EnvelopeEnc, type EnvelopeKind, type ExpireSelector, type ExplainDependencyScope, type ExplainIdentity, type ExplainReaderState, type ExplainScope, type ExplainTtl, type ExplainVerdict, type ExplainedDependency, type Explanation, type FactoryCtx, FactorySettledError, FencedError, type GetOptions, type GetOrSetEntryOptions, type GetOrSetOptions, type GracedInfo, HttpError, InvalidDurationError, InvalidTagError, type L3Budget, type L3Emission, type L3Ineligibility, type Lock, type LockHandle, type MatchedHint, type MemoryOptions, NotImplementedError, type OriginLoadGuard, type PurgeResult, type ReadKind, type Registry, type RegistryAck, RegistryUnavailableError, type RenderCollector, type RequestContext, type Rng, type Scope, type SinkErrorHook, type Store, type StoreMetadata, type StoreValue, type StoreWriteError, type StoreWriteOptions, type StrongDegradedReason, type Subscription, TELEMETRY_EVENTS, type Tag, type TagChange, type TagKnowledge, type TagPart, type TelemetryConfig, type TelemetryEvent, type TelemetryEventName, type TelemetrySink, type Tier, type UnknownPolicy, UnknownTagError, type Validity, type Watermark, compound, createCache, duration, globalTag, httpError, isRetriableHttp, isStoreWriteError, memory, t };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { A as UnknownTagError, C as FactorySettledError, D as InvalidTagError, E as InvalidDurationError, O as NotImplementedError, S as CacheTimeoutError, T as HttpError, _ as t, c as isRetriableHttp, d as memory, g as globalTag, h as compound, k as RegistryUnavailableError, l as duration, p as TELEMETRY_EVENTS, r as createCache, s as httpError, u as isStoreWriteError, w as FencedError } from "./cache-Z4cJzPmm.js";
+export { CacheTimeoutError, FactorySettledError, FencedError, HttpError, InvalidDurationError, InvalidTagError, NotImplementedError, RegistryUnavailableError, TELEMETRY_EVENTS, UnknownTagError, compound, createCache, duration, globalTag, httpError, isRetriableHttp, isStoreWriteError, memory, t };

package/package.json

@@ -1,6 +1,99 @@
 {
   "name": "@astilba/cache",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Portable TypeScript caching with tag invalidation, stale-if-error resilience, and privacy scopes.",
+  "homepage": "https://astilba.com/docs/cache/",
+  "bugs": {
+    "url": "https://github.com/astilbahq/astilba/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/astilbahq/astilba.git",
+    "directory": "packages/cache"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./cloudflare": {
+      "types": "./dist/adapters/cloudflare/index.d.ts",
+      "default": "./dist/adapters/cloudflare/index.js"
+    },
+    "./react-router": {
+      "types": "./dist/adapters/react-router/index.d.ts",
+      "default": "./dist/adapters/react-router/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.4",
+    "@cloudflare/vitest-pool-workers": "0.18.3",
+    "@fast-check/vitest": "^0.4.1",
+    "@stryker-mutator/core": "9.6.1",
+    "@stryker-mutator/vitest-runner": "9.6.1",
+    "@types/node": "24.13.2",
+    "@types/react": "19.2.17",
+    "@vitest/coverage-istanbul": "4.1.11",
+    "eslint-plugin-github": "6.0.0",
+    "eslint-plugin-sonarjs": "4.1.0",
+    "fast-check": "^4.8.0",
+    "knip": "6.24.0",
+    "miniflare": "4.20260708.0",
+    "oxfmt": "0.64.0",
+    "oxlint": "1.79.0",
+    "oxlint-tsgolint": "7.0.2001",
+    "publint": "0.3.21",
+    "react": "19.2.7",
+    "react-router": "8.3.0",
+    "typescript": "6.0.3",
+    "ultracite": "7.9.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.0",
+    "vite-plus": "0.3.0",
+    "vitest": "4.1.11",
+    "wrangler": "4.109.0",
+    "yaml": "2.9.0",
+    "@astilba/harness": "0.0.0"
+  },
+  "peerDependencies": {
+    "react": "19.2.7",
+    "react-router": "8.3.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-router": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "vp pack",
+    "build:apps": "pnpm --dir ../../fixtures/cache-react-router run build && pnpm --dir ../../apps/cache-demo run build",
+    "check": "for d in . ../cache-harness ../../apps/cache-demo; do (cd $d && oxfmt --config oxfmt.config.ts --disable-nested-config --check . && oxlint --config oxlint.config.ts --disable-nested-config --type-aware --type-check .) || exit 1; done",
+    "fix": "for d in . ../cache-harness ../../apps/cache-demo; do (cd $d && oxfmt --config oxfmt.config.ts --disable-nested-config --write . && oxlint --config oxlint.config.ts --disable-nested-config --type-aware --type-check --fix .) || exit 1; done",
+    "test": "vp test",
+    "test:unit": "vp test run --project unit --project harness",
+    "test:invariants": "vitest run --project invariants",
+    "test:mutation": "stryker run",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.config.json && tsc -p test/integration/tsconfig.json --noEmit && pnpm --filter @astilba/harness --filter @astilba/demo --filter @astilba/rr-fixture -r exec tsc --noEmit",
+    "types:integration": "cd test/integration && wrangler types",
+    "lint:publish": "node scripts/check-package.mjs",
+    "knip": "pnpm --dir ../.. exec knip --workspace packages/cache --workspace packages/cache-harness --workspace apps/cache-demo --workspace fixtures/cache-react-router",
+    "knip:production": "pnpm knip --production",
+    "verify:toolchain": "node scripts/verify-toolchain.mjs",
+    "verify": "pnpm verify:toolchain && pnpm check && pnpm typecheck && pnpm exec vitest run && pnpm exec vp test run --project unit --project harness --coverage && pnpm lint:publish && pnpm knip && pnpm knip:production && pnpm build:apps && node scripts/boot-smoke.mjs && node scripts/module-scope-boot.mjs && node scripts/demo-boot-witness.mjs && node scripts/demo-typed-routes.mjs"
+  }
 }