@thomasfosterau/pulpit 0.0.0 → 0.1.0

package/src/internal/filter-columns.ts

@@ -0,0 +1,50 @@
+/**
+ * **A list filter's columns, renamed**: `./edges` qualifies a leaf's filter
+ * with an end's alias through it, so a store can render that filter against
+ * the view it joined under the alias.
+ *
+ * Internal: not a package entry point (absent from `package.json`
+ * `exports`) and excluded from the generated API docs (`docgen.json`).
+ *
+ * @internal
+ */
+import * as Match from "effect/Match";
+import type { ListFilter } from "../filter.ts";
+
+/**
+ * Every column of `filter` rewritten by `rename`; the tree's shape and every
+ * comparand are kept. Exhaustive over the node kinds, so a new kind cannot
+ * slip through with its column unrenamed.
+ */
+export const renameColumns = <Following>(
+  filter: ListFilter<Following>,
+  rename: (column: string) => string,
+): ListFilter<Following> =>
+  Match.value(filter).pipe(
+    Match.discriminatorsExhaustive("kind")({
+      always: (node): ListFilter<Following> => node,
+      never: (node): ListFilter<Following> => node,
+      eq: (node): ListFilter<Following> => ({ ...node, column: rename(node.column) }),
+      ne: (node): ListFilter<Following> => ({ ...node, column: rename(node.column) }),
+      in: (node): ListFilter<Following> => ({ ...node, column: rename(node.column) }),
+      notIn: (node): ListFilter<Following> => ({ ...node, column: rename(node.column) }),
+      gt: (node): ListFilter<Following> => ({ ...node, column: rename(node.column) }),
+      gte: (node): ListFilter<Following> => ({ ...node, column: rename(node.column) }),
+      lt: (node): ListFilter<Following> => ({ ...node, column: rename(node.column) }),
+      lte: (node): ListFilter<Following> => ({ ...node, column: rename(node.column) }),
+      anyOf: (node): ListFilter<Following> => ({ ...node, column: rename(node.column) }),
+      noneOf: (node): ListFilter<Following> => ({ ...node, column: rename(node.column) }),
+      isNull: (node): ListFilter<Following> => ({ ...node, column: rename(node.column) }),
+      published: (node): ListFilter<Following> => ({ ...node, column: rename(node.column) }),
+      notPublished: (node): ListFilter<Following> => ({ ...node, column: rename(node.column) }),
+      locale: (node): ListFilter<Following> => ({ ...node, column: rename(node.column) }),
+      and: (node): ListFilter<Following> => ({
+        kind: "and",
+        filters: node.filters.map((part) => renameColumns(part, rename)),
+      }),
+      or: (node): ListFilter<Following> => ({
+        kind: "or",
+        filters: node.filters.map((part) => renameColumns(part, rename)),
+      }),
+    }),
+  );

package/src/internal/list-order.ts

@@ -0,0 +1,117 @@
+/**
+ * **The kernel's value and row orders**: the code-point string order that
+ * `./filter`'s comparison arms share with SQL's `COLLATE "C"`, and the list
+ * order the in-memory `LeafStore` fake sorts by (pulpit#112), so the fake and
+ * the filter never compare a string two ways.
+ *
+ * Internal: not a package entry point (absent from `package.json`
+ * `exports`) and excluded from the generated API docs (`docgen.json`).
+ * Typed structurally, so it never imports `./subtype`.
+ *
+ * @internal
+ */
+import * as Array from "effect/Array";
+import * as Order from "effect/Order";
+import * as Predicate from "effect/Predicate";
+import type { ColumnValue } from "../version-chain.ts";
+
+/**
+ * Strings by code point, as SQL's `"C"` collation orders them over UTF-8.
+ * JavaScript's `<` compares UTF-16 code units instead, which puts an astral
+ * character (a surrogate pair, from U+D800) before U+E000–U+FFFF.
+ */
+export const byCodePoint: Order.Order<string> = Order.mapInput(
+  Order.Array(Order.Number),
+  (text: string) => Array.map(Array.fromIterable(text), (char) => char.codePointAt(0) ?? 0),
+);
+
+/**
+ * Numbers as PostgreSQL's `float8` sorts them: `NaN` equal to itself and
+ * after every number, where Effect's `Order.Number` puts it first.
+ */
+const byNumber: Order.Order<number> = Order.make((self, that) => {
+  if (Number.isNaN(self)) return Number.isNaN(that) ? 0 : 1;
+  return Number.isNaN(that) ? -1 : Order.Number(self, that);
+});
+
+/**
+ * One kind of sort-key value: its guard and its order, the order lifted to
+ * every {@link ColumnValue} (two values the guard doesn't both admit tie).
+ */
+const kind = <A extends ColumnValue>(
+  is: (value: ColumnValue) => value is A,
+  order: Order.Order<A>,
+) => ({
+  is,
+  order: Order.make<ColumnValue>((self, that) => (is(self) && is(that) ? order(self, that) : 0)),
+});
+
+/**
+ * The kinds of sort-key value, each sorted as PostgreSQL sorts its type: a
+ * boolean `false` first, a number numerically, a `bigint` by value, a
+ * string by code point, a `Date` by its instant (an invalid one as `NaN`).
+ */
+const kinds = [
+  kind(Predicate.isBoolean, Order.Boolean),
+  kind(Predicate.isNumber, byNumber),
+  kind(Predicate.isBigInt, Order.BigInt),
+  kind(Predicate.isString, byCodePoint),
+  kind(
+    Predicate.isDate,
+    Order.mapInput(byNumber, (date: Date) => date.getTime()),
+  ),
+];
+
+/**
+ * A value's place in {@link kinds}; a JSON object or array comes after
+ * them all. Two values of different kinds sort by it, which is outside the
+ * contract (a SQL column has one type), so it only keeps the fake's order
+ * total and deterministic.
+ */
+const kindOf = (value: ColumnValue): number => {
+  const index = kinds.findIndex((each) => each.is(value));
+  return index === -1 ? kinds.length : index;
+};
+
+/**
+ * Two non-`NULL` sort-key values: by kind, then by that kind's order. Two
+ * JSON objects or arrays tie, leaving the order to the next key.
+ */
+const byValue: Order.Order<ColumnValue> = Order.make((self, that) => {
+  const left = kindOf(self);
+  const right = kindOf(that);
+  if (left !== right) return Order.Number(left, right);
+  const same = kinds[left];
+  return same === undefined ? 0 : same.order(self, that);
+});
+
+/** One order key, structurally (`./subtype`'s `ListOrder` fits). */
+interface OrderKey {
+  readonly column: string;
+  readonly direction: "asc" | "desc";
+}
+
+/** A row as the order reads it: its `id` and its columns by name. */
+type SortRow = { readonly id: string; readonly [column: string]: ColumnValue };
+
+/** One key: its column's values in its direction, a `NULL` or absent column last in both. */
+const byKey = (key: OrderKey): Order.Order<SortRow> => {
+  const values = key.direction === "desc" ? Order.flip(byValue) : byValue;
+  return Order.make((self, that) => {
+    const left = self[key.column] ?? null;
+    const right = that[key.column] ?? null;
+    if (left === null) return right === null ? 0 : 1;
+    return right === null ? -1 : values(left, right);
+  });
+};
+
+/** The closing key every list order ends with: `id` ascending, by code point. */
+const byId: Order.Order<SortRow> = Order.mapInput(byCodePoint, (row: SortRow) => row.id);
+
+/**
+ * The total order a list renders as `ORDER BY <key> <direction> NULLS LAST,
+ * …, id ASC`: each key in turn, a `NULL` (or absent) column after every
+ * value in either direction, then `id` ascending, so no two rows tie.
+ */
+export const rowOrder = (keys: ReadonlyArray<OrderKey>): Order.Order<SortRow> =>
+  Order.combineAll([...Array.map(keys, byKey), byId]);

package/src/internal/owned-columns.ts

@@ -0,0 +1,140 @@
+/**
+ * **The owned leaf's row reading**, shared by `./subtype` and `./edges` so
+ * the two cannot read the same view or row differently: the declared-column
+ * check (pulpit#79), the facts read off a row (pulpit#80), and the predicate
+ * over those facts, which `canViewOwned` delegates to (pulpit#85).
+ *
+ * Internal: not a package entry point (absent from `package.json`
+ * `exports`) and excluded from the generated API docs (`docgen.json`).
+ * Typed structurally, so it never imports `./subtype`.
+ *
+ * @internal
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Predicate from "effect/Predicate";
+import * as Schema from "effect/Schema";
+import { Visibility } from "../content.ts";
+import type { ColumnValue } from "../version-chain.ts";
+
+/** The owned access declaration's column names, structurally (`./subtype`'s owned `LeafAccess` fits). */
+interface OwnedColumns {
+  readonly ownerColumn: string;
+  readonly visibilityColumn: string;
+  readonly draftColumn: Option.Option<string>;
+  readonly moderationColumn: Option.Option<string>;
+}
+
+/**
+ * The facts {@link canViewOwnedRow} reads off an owned row: `./subtype`'s
+ * `OwnedFacts`, except that the owner may be absent. A row whose owner
+ * column holds no string has no owner (pulpit#85).
+ */
+interface OwnedRowFacts {
+  readonly ownerId: Option.Option<string>;
+  readonly visibility: Visibility;
+  readonly draft: boolean;
+  /** Under review or rejected: a moderated row whose state is not exactly `approved` (pulpit#154). */
+  readonly unapproved: boolean;
+}
+
+/** The parts of `./subtype`'s viewer, policy and follower seam the predicate reads, structurally. */
+interface Account {
+  readonly id: string;
+}
+interface PrivateRung<A> {
+  readonly canViewPrivate: (account: A) => boolean;
+}
+interface IsFollower<R> {
+  readonly isFollower: (followerId: string, ownerId: string) => Effect.Effect<boolean, never, R>;
+}
+
+const isVisibility = Schema.is(Visibility);
+
+/**
+ * Whether the view carries every column an owned leaf declares (owner,
+ * visibility and, when declared, draft and moderation state). An owned leaf whose view lacks one
+ * reads no row: `ownedListFilter` lists nothing, and `defineSubtype`'s
+ * `get` / `getMany` and `./edges`' `canViewEndpoint` show nothing. Fail
+ * closed (`SEC-AUTH-ENUM-001`). Never throws.
+ *
+ * @internal
+ */
+export const declaresColumns = (access: OwnedColumns, viewColumns: ReadonlySet<string>): boolean =>
+  [
+    access.ownerColumn,
+    access.visibilityColumn,
+    ...Option.toArray(access.draftColumn),
+    ...Option.toArray(access.moderationColumn),
+  ].every((column) => viewColumns.has(column));
+
+/**
+ * Read an owned row's facts for `canViewOwned`, in `defineSubtype`'s
+ * `get` / `getMany` and `./edges`' `canViewEndpoint`. Each reading fails
+ * closed where `ownedListFilter` does (`SEC-AUTH-ENUM-001`): a visibility
+ * outside the enum (a dropped projection, a schema drift) reads as
+ * `private`, since the filter's `eq(visibility, "public")` arm lists only
+ * `public`; a draft column holding anything but an explicit `false` (a
+ * `NULL`, an absent key, a value outside the type) reads as a draft, since
+ * its `eq(draft, false)` arms list only `false`. A leaf without the draft
+ * axis reads `draft: false`. A moderation column holding anything but
+ * exactly `"approved"` reads as unapproved, since the filter's
+ * `eq(moderation, "approved")` arms list only `approved`; a leaf without the
+ * axis reads `unapproved: false`. An owner column holding anything but a string
+ * (a `NULL`, an absent key, a value outside the type) reads as no owner,
+ * never as its `String` form (pulpit#85; see pulpit#75): its `eq(owner, …)`
+ * and `in(owner, following)` arms match no `NULL`. Callers check
+ * {@link declaresColumns} first. Never throws.
+ *
+ * @internal
+ */
+export const ownedFacts = (
+  access: OwnedColumns,
+  row: { readonly [column: string]: ColumnValue },
+): OwnedRowFacts => ({
+  ownerId: Option.liftPredicate(row[access.ownerColumn], Predicate.isString),
+  visibility: Option.getOrElse(
+    Option.liftPredicate(row[access.visibilityColumn], isVisibility),
+    (): Visibility => "private",
+  ),
+  draft: Option.match(access.draftColumn, {
+    onNone: () => false,
+    onSome: (column) => row[column] !== false,
+  }),
+  unapproved: Option.match(access.moderationColumn, {
+    onNone: () => false,
+    onSome: (column) => row[column] !== "approved",
+  }),
+});
+
+/**
+ * The owned-material read predicate over {@link ownedFacts}: `canViewOwned`
+ * in `./subtype` is this with a present owner, and `defineSubtype`'s
+ * `get` / `getMany` and `./edges`' `canViewEndpoint` call it directly. A
+ * row with no owner skips the owner arm and the follower check, so no
+ * viewer's id matches it and the follower seam is never asked about it:
+ * it is visible only when it is `public`, not a draft and not unapproved, or to the
+ * view-private rung, as `ownedListFilter` lists it (`SEC-AUTH-ENUM-001`).
+ * Never fails.
+ *
+ * @internal
+ */
+export const canViewOwnedRow = <A extends Account, R>(
+  viewer: Option.Option<A>,
+  policy: PrivateRung<A>,
+  followers: IsFollower<R>,
+  row: OwnedRowFacts,
+): Effect.Effect<boolean, never, R> => {
+  if (!row.draft && !row.unapproved && row.visibility === "public") return Effect.succeed(true);
+  if (Option.isNone(viewer)) return Effect.succeed(false);
+  const account = viewer.value;
+  if (Option.contains(row.ownerId, account.id)) return Effect.succeed(true);
+  if (policy.canViewPrivate(account)) return Effect.succeed(true);
+  // Not the owner, not privileged: a draft, or a row not approved, is hidden whatever its visibility.
+  if (row.draft || row.unapproved) return Effect.succeed(false);
+  if (row.visibility === "private") return Effect.succeed(false);
+  return Option.match(row.ownerId, {
+    onNone: () => Effect.succeed(false),
+    onSome: (ownerId) => followers.isFollower(account.id, ownerId),
+  });
+};

package/src/internal/plain-rows.ts

@@ -0,0 +1,54 @@
+/**
+ * The pieces `./proposals` and `./moderation`'s reports share: both are
+ * plain-row families (not nodes) with a sign-in gate, a write clock and a
+ * page query narrowed to one leaf type, an optional target and an
+ * optional status.
+ *
+ * @module pulpit/internal/plain-rows
+ */
+
+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 { always, and, eq, type ListFilter } from "../filter.ts";
+import { MAX_PAGE_LIMIT, Unauthorized, type Viewer, type ViewerAccount } from "../subtype.ts";
+
+/** The write clock: the current instant, as the `Date` a row stores. */
+export const nowDate: Effect.Effect<Date> = Effect.map(Clock.currentTimeMillis, (millis) =>
+  DateTime.toDate(DateTime.makeUnsafe(millis)),
+);
+
+/** The signed-in account, or `Unauthorized`. */
+export const signedIn = <R>(
+  viewer: Effect.Effect<Viewer, never, R>,
+): Effect.Effect<ViewerAccount, Unauthorized, R> =>
+  Effect.flatMap(viewer, (account) => Effect.fromOption(account, () => new Unauthorized()));
+
+/**
+ * A list request's store query: the leaf's rows under the viewer's `scope`,
+ * narrowed by target and status when asked, the page clamped to
+ * `MAX_PAGE_LIMIT` (`SEC-INPUT-003`).
+ */
+export const plainRowQuery = <Status extends string>(
+  type: string,
+  scope: ListFilter<never>,
+  request: {
+    readonly targetId: Option.Option<string>;
+    readonly status: Option.Option<Status>;
+    readonly limit: number;
+    readonly offset: number;
+  },
+) => ({
+  where: and<never>(
+    eq("targetType", type),
+    scope,
+    Option.match(request.targetId, { onNone: () => always, onSome: (id) => eq("targetId", id) }),
+    Option.match(request.status, {
+      onNone: () => always,
+      onSome: (status) => eq("status", status),
+    }),
+  ),
+  limit: Math.max(1, Math.min(Math.trunc(request.limit), MAX_PAGE_LIMIT)),
+  offset: Math.max(0, Math.trunc(request.offset)),
+});

package/src/internal/reference-columns.ts

@@ -0,0 +1,156 @@
+/**
+ * **The reference leaf's privacy arm** (`PUB-009`), shared by `./subtype`
+ * and `./edges` so a reference row is read one way: as a list filter
+ * ({@link referenceListFilter}, behind `referencePrivacyFilter`, the subtype
+ * `list` and `./edges`' `endpointFilter`) and as a row predicate
+ * ({@link canViewReferenceRow}, behind `defineSubtype`'s `visibleRow` and
+ * `./edges`' `canViewEndpoint`). Before pulpit#92 each module spelled the
+ * predicate for itself.
+ *
+ * The row's facts are read by `ownedFacts`, so an owner-like value that is
+ * not a string reads as no owner and never reaches the follower seam
+ * (pulpit#85, pulpit#100).
+ *
+ * Internal: not a package entry point (absent from `package.json`
+ * `exports`) and excluded from the generated API docs (`docgen.json`).
+ * Typed structurally, so it never imports `./subtype`.
+ *
+ * @internal
+ */
+import * as Effect from "effect/Effect";
+import * as Match from "effect/Match";
+import * as Option from "effect/Option";
+import { always, and, eq, isIn, or, type ListFilter } from "../filter.ts";
+import type { ColumnValue } from "../version-chain.ts";
+import { ownedFacts } from "./owned-columns.ts";
+
+/** The reference access declaration, structurally (`./subtype`'s reference `LeafAccess` fits). */
+interface ReferenceColumns {
+  // oxlint-disable-next-line effect/prefer-option-over-null -- mirrors `./subtype`'s reference `LeafAccess`, whose optional field is `?: T | undefined` (AGENTS.md → Conventions)
+  readonly followersOfColumn?: string | undefined;
+}
+
+/** The parts of `./subtype`'s viewer, policy, follower seam and read scope the arm reads, structurally. */
+interface Account {
+  readonly id: string;
+}
+interface PrivateRung<A> {
+  readonly canViewPrivate: (account: A) => boolean;
+}
+interface IsFollower<R> {
+  readonly isFollower: (followerId: string, ownerId: string) => Effect.Effect<boolean, never, R>;
+}
+type Scope<Following> =
+  | { readonly kind: "all" }
+  | { readonly kind: "public" }
+  | { readonly kind: "member"; readonly userId: string; readonly following: Following };
+
+/** The reference axis's one column; a view without it rides no privacy axis. */
+const VISIBILITY = "visibility";
+
+/**
+ * The column whose followers may read a `followers` row, when the leaf
+ * declares one and the view carries it. A declared column the view lacks
+ * reads as none: the followers arm then matches nothing (fail closed).
+ */
+const followersColumn = (
+  access: ReferenceColumns,
+  viewColumns: ReadonlySet<string>,
+): Option.Option<string> =>
+  Option.filter(Option.fromUndefinedOr(access.followersOfColumn), (column) =>
+    viewColumns.has(column),
+  );
+
+/**
+ * The reference privacy arm as a list filter: `always` over a view without a
+ * `visibility` column or for the view-private rung (`scope.kind === "all"`);
+ * otherwise `visibility = 'public'`, and for a signed-in viewer also
+ * `visibility = 'followers' AND (<followersOfColumn> = <viewer> OR
+ * <followersOfColumn> IN (<following>))` when the leaf declares that column
+ * and the view carries it (pulpit#92): the account the column names and its
+ * followers read its `followers` rows. Its `private` rows stay the
+ * view-private rung's alone. Never throws.
+ *
+ * @internal
+ */
+export const referenceListFilter = <Following>(
+  access: ReferenceColumns,
+  viewColumns: ReadonlySet<string>,
+  scope: Scope<Following>,
+): ListFilter<Following> => {
+  if (!viewColumns.has(VISIBILITY)) return always;
+  const column = followersColumn(access, viewColumns);
+  return Match.value(scope).pipe(
+    Match.discriminatorsExhaustive("kind")({
+      all: (): ListFilter<Following> => always,
+      public: (): ListFilter<Following> => eq(VISIBILITY, "public"),
+      member: (member): ListFilter<Following> =>
+        Option.match(column, {
+          onNone: (): ListFilter<Following> => eq(VISIBILITY, "public"),
+          onSome: (followed) =>
+            or<Following>(
+              eq(VISIBILITY, "public"),
+              and<Following>(
+                eq(VISIBILITY, "followers"),
+                or<Following>(eq(followed, member.userId), isIn(followed, member.following)),
+              ),
+            ),
+        }),
+    }),
+  );
+};
+
+/**
+ * The reference privacy arm as a row predicate, the same facts as
+ * {@link referenceListFilter}: a view without a `visibility` column shows
+ * the row; otherwise it shows when its visibility is exactly `public`, to
+ * the view-private rung, or, when it is exactly `followers` and the leaf
+ * declares a followers column the view carries, to the signed-in account
+ * that column names and to its followers, as the follower seam answers
+ * (pulpit#92). That account's `private` rows stay the view-private rung's
+ * alone. A column value that is not a string names no account, so it never
+ * matches the viewer and the seam is never asked about it (pulpit#85,
+ * pulpit#100). Anything else is hidden, which the
+ * caller answers as `NodeNotFound` (`SEC-AUTH-ENUM-001`). The soft-delete
+ * axis is the caller's. Never fails.
+ *
+ * @internal
+ */
+export const canViewReferenceRow = <A extends Account, R>(
+  access: ReferenceColumns,
+  viewColumns: ReadonlySet<string>,
+  viewer: Option.Option<A>,
+  policy: PrivateRung<A>,
+  followers: IsFollower<R>,
+  row: { readonly [column: string]: ColumnValue },
+): Effect.Effect<boolean, never, R> => {
+  if (!viewColumns.has(VISIBILITY)) return Effect.succeed(true);
+  const visibility = row[VISIBILITY];
+  if (visibility === "public") return Effect.succeed(true);
+  if (Option.isNone(viewer)) return Effect.succeed(false);
+  const account = viewer.value;
+  if (policy.canViewPrivate(account)) return Effect.succeed(true);
+  if (visibility !== "followers") return Effect.succeed(false);
+  return Option.match(followersColumn(access, viewColumns), {
+    onNone: () => Effect.succeed(false),
+    onSome: (column) =>
+      Option.match(
+        ownedFacts(
+          {
+            ownerColumn: column,
+            visibilityColumn: VISIBILITY,
+            draftColumn: Option.none(),
+            moderationColumn: Option.none(),
+          },
+          row,
+        ).ownerId,
+        {
+          onNone: () => Effect.succeed(false),
+          onSome: (ownerId) =>
+            ownerId === account.id
+              ? Effect.succeed(true)
+              : followers.isFollower(account.id, ownerId),
+        },
+      ),
+  });
+};