@thomasfosterau/pulpit 0.0.0-stage → 0.1.0

package/dist/paths.js

@@ -0,0 +1,165 @@
+/**
+ * **Routable content** — a leaf's path claims, tied to its version chain,
+ * the slug aliases a path change leaves behind, and the gated resolution of
+ * a path to a node or a redirect.
+ *
+ * The behavioural spec is gardeneria's `apps/api/src/operations/pages.ts`
+ * and `packages/database/src/tables/pages.ts` (one live page per canonical
+ * path, old slugs kept in `page_slugs` and answered with a 301). A `#NNN`
+ * here names a gardeneria issue.
+ *
+ * ## The model (owner decision on pulpit#57)
+ *
+ * - **A claim lives on the root node**: one path per content item. The
+ *   locale is chosen when the resolved node is read, never by the path, so a
+ *   slug translation is not a claim of its own (pulpit#56's model (b)).
+ * - **Claims follow the node's lifecycle.** A write that leaves the node
+ *   live claims the path its new state holds in the leaf's path column; a
+ *   tombstone, or a state with no path, frees the claim; a restore re-claims
+ *   its path, or fails {@link PathTaken} when another node holds it now.
+ * - **A path change records an alias**: the old path resolves as a redirect
+ *   to the new one, for as long as no other node claims it.
+ * - **Resolution is gated** (`SEC-AUTH-ENUM-001`): {@link RoutableOps.resolve}
+ *   reads the node through the leaf's own `get`, so a hidden node's path,
+ *   and an alias to a hidden node, is {@link PathNotFound}, never a redirect.
+ *
+ * Free-form redirects (patterns, a 404 log) are the site's. The path's
+ * syntax is the leaf attribute's schema (effect-schema-ext's `Ids.slug`, once
+ * it publishes).
+ *
+ * @copyright Thomas Foster
+ * @module pulpit/paths
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect";
+import * as Equivalence from "effect/Equivalence";
+import * as Option from "effect/Option";
+import * as Predicate from "effect/Predicate";
+import * as Schema from "effect/Schema";
+// ── The path-store seam ───────────────────────────────────────────────
+/**
+ * Another node holds the path canonically: the wire's 409. It names the
+ * path, never the holder, so it says only that the path is taken, as a
+ * unique-key conflict does, whoever holds it.
+ *
+ * @since 0.1.0
+ */
+export class PathTaken extends Schema.TaggedError()("PathTaken", {
+    path: Schema.String,
+}) {
+}
+/**
+ * No node the viewer can read answers to the path: the wire's 404. A path
+ * nobody claims, one whose node is hidden from the viewer, and an alias to a
+ * hidden node all answer this, alike (`SEC-AUTH-ENUM-001`).
+ *
+ * @since 0.1.0
+ */
+export class PathNotFound extends Schema.TaggedError()("PathNotFound", {
+    path: Schema.String,
+}) {
+}
+/**
+ * Make a leaf routable (pulpit#57): its writes keep the node's path claim in
+ * step with its chain, and {@link RoutableOps.resolve} answers a path through
+ * the leaf's own read gate. After each write's append, in the same
+ * transaction, the claim follows the state the write landed at: a live state
+ * with a path claims it (a change leaves the old path as an alias; another
+ * node's claim fails {@link PathTaken}), and a tombstone or a state with no
+ * path frees it. A restore into a path another node took meanwhile therefore
+ * fails `PathTaken`, and its append rolls back with it. Wrap the result with
+ * `./subtype`'s `subtypeHandlers` as the leaf's own operations, so its
+ * `transact` covers the claims.
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import * as Effect from "effect/Effect";
+ * import * as Option from "effect/Option";
+ * import { routable } from "@thomasfosterau/pulpit/paths";
+ * import { defineSubtype, nobodyFollows } from "@thomasfosterau/pulpit/subtype";
+ * import {
+ *   makeInMemoryChainStore,
+ *   makeInMemoryLeafStore,
+ *   makeInMemoryPathStore,
+ * } from "@thomasfosterau/pulpit/testing";
+ * import * as HashSet from "effect/HashSet";
+ *
+ * const chain = makeInMemoryChainStore();
+ * const pages = routable(
+ *   defineSubtype({
+ *     type: "pages",
+ *     access: { kind: "reference" },
+ *     chain,
+ *     leaves: makeInMemoryLeafStore(chain, { columns: ["slug"] }),
+ *     viewer: Effect.succeed(Option.some({ id: "editor", role: "admin" })),
+ *     policy: {
+ *       canViewPrivate: () => true,
+ *       canViewDeleted: () => true,
+ *       canModerate: () => true,
+ *       canWriteCorpus: () => true,
+ *     },
+ *     followers: nobodyFollows(HashSet.empty<string>()),
+ *     toResource: (row) => ({ id: row.id, slug: row["slug"] }),
+ *   }),
+ *   { column: "slug", paths: makeInMemoryPathStore(), chain },
+ * );
+ * const program = Effect.gen(function* () {
+ *   const { id } = yield* pages.create({ id: Option.none(), state: { slug: "about" } });
+ *   yield* pages.update({ id, patch: { slug: "about-us" } });
+ *   return yield* pages.resolve("about");
+ * });
+ * const resolved = Effect.runSync(program);
+ * strictEqual(resolved.kind === "redirect" && resolved.path, "about-us");
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const routable = (ops, config) => {
+    const { column, paths, chain } = config;
+    // The claim the written state calls for: its path while it is live, none
+    // for a tombstone or a state whose path column holds no string.
+    const follow = ({ id, version }) => Effect.gen(function* () {
+        const written = yield* chain.snapshot(id, version);
+        const path = Option.flatMap(written, (snapshot) => snapshot.action === "delete"
+            ? Option.none()
+            : Option.liftPredicate(snapshot.state[column], Predicate.isString));
+        const held = yield* paths.canonicalOf(id);
+        if (Option.makeEquivalence(Equivalence.String)(path, held))
+            return;
+        yield* Option.match(path, {
+            onNone: () => paths.release(id),
+            onSome: (claimed) => paths.claim(id, claimed),
+        });
+    });
+    const claiming = (write) => Effect.tap(write, follow);
+    const resolve = Effect.fn(`${ops.type}.resolve`)(function* (path) {
+        const notFound = new PathNotFound({ path });
+        const entry = yield* paths.lookup(path);
+        if (Option.isNone(entry))
+            return yield* notFound;
+        const { nodeId, canonical } = entry.value;
+        // The leaf's own gate: a hidden node answers exactly as no node.
+        const resource = yield* ops
+            .get(nodeId)
+            .pipe(Effect.catchTag("NodeNotFound", () => Effect.fail(notFound)));
+        if (canonical)
+            return { kind: "node", id: nodeId, resource };
+        const target = yield* paths.canonicalOf(nodeId);
+        return yield* Option.match(target, {
+            onNone: () => Effect.fail(notFound),
+            onSome: (to) => Effect.succeed({ kind: "redirect", id: nodeId, path: to }),
+        });
+    });
+    return {
+        ...ops,
+        create: (input) => claiming(ops.create(input)),
+        update: (input) => claiming(ops.update(input)),
+        restore: (input) => claiming(ops.restore(input)),
+        // A delete over a tombstone wrote nothing, and its claim is already free.
+        delete: (id, precondition) => Effect.tap(ops.delete(id, precondition), (written) => written.alreadyDeleted ? Effect.void : paths.release(id)),
+        restoreVersion: (id, version, precondition) => claiming(ops.restoreVersion(id, version, precondition)),
+        resolve,
+    };
+};
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

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