@astronox/core 0.2.4 → 0.3.0

package/src/content/admin.ts

@@ -0,0 +1,354 @@
+import type { AdminResource } from '../admin';
+import type { AuthActor } from '../auth';
+import type {
+  ContentDocument,
+  ContentDocumentAdminRepository,
+  ContentDocumentDraft,
+  ContentOrder,
+  ContentPlacement,
+  ContentPlacementAdminRepository,
+  ContentPlacementDraft,
+} from './contracts';
+
+type IndexInput = { cursor?: string; limit?: number } | undefined;
+
+export type ContentAdminSnapshotReader<
+  TPlacement extends ContentPlacement,
+  TDocument extends ContentDocument,
+> = {
+  getDocuments(actor: AuthActor): readonly TDocument[] | null;
+  getPlacements(actor: AuthActor): readonly TPlacement[] | null;
+};
+
+export type ContentAdminErrors = {
+  documentNotFound: string;
+  documentSlugExists: string;
+  placementInUse: string;
+  placementKeyExists: string;
+  placementNotFound: string;
+};
+
+export function createContentAdminResources<
+  TPlacement extends ContentPlacement,
+  TDocument extends ContentDocument,
+  TPlacementDraft extends ContentPlacementDraft,
+  TDocumentDraft extends ContentDocumentDraft,
+>({
+  assertRootSlug,
+  documents,
+  errors,
+  parseDocumentDraft,
+  parsePlacementDraft,
+  placements,
+  requireWriteAccess,
+  rootPlacementKey,
+  snapshots,
+}: {
+  assertRootSlug?(slug: string): void;
+  documents: ContentDocumentAdminRepository<TDocument, TDocumentDraft>;
+  errors: ContentAdminErrors;
+  parseDocumentDraft(input: unknown): TDocumentDraft;
+  parsePlacementDraft(input: unknown): TPlacementDraft;
+  placements: ContentPlacementAdminRepository<TPlacement, TPlacementDraft>;
+  requireWriteAccess(actor: AuthActor): void;
+  rootPlacementKey?: string;
+  snapshots: ContentAdminSnapshotReader<TPlacement, TDocument>;
+}) {
+  const placementResource: AdminResource<
+    TPlacement,
+    TPlacementDraft,
+    TPlacementDraft,
+    IndexInput
+  > = {
+    getIndex: (input) => placements.getIndex(input),
+    getDetail: (input) => placements.getDetail(input),
+    async create(input, actor) {
+      requireWriteAccess(actor);
+      const draft = parsePlacementDraft(input);
+      const allPlacements = await loadAll(
+        placements,
+        snapshots.getPlacements(actor),
+      );
+      assertUniquePlacementKey(allPlacements, draft.key, errors);
+      return placements.create(draft);
+    },
+    async update({ id, value }, actor) {
+      requireWriteAccess(actor);
+      const draft = parsePlacementDraft(value);
+      const allPlacements = await loadAll(
+        placements,
+        snapshots.getPlacements(actor),
+      );
+      const current = allPlacements.find((placement) => placement.id === id);
+      if (!current) throw new Error(errors.placementNotFound);
+      if (samePlacement(current, draft)) return current;
+      assertUniquePlacementKey(allPlacements, draft.key, errors, id);
+      if (
+        rootPlacementKey &&
+        draft.key === rootPlacementKey &&
+        assertRootSlug
+      ) {
+        const allDocuments = await loadAll(
+          documents,
+          snapshots.getDocuments(actor),
+        );
+        allDocuments
+          .filter((document) => document.placementId === id)
+          .forEach((document) => assertRootSlug(document.slug));
+      }
+      return placements.update({ id, value: draft });
+    },
+    async delete({ id }, actor) {
+      requireWriteAccess(actor);
+      const allDocuments = await loadAll(
+        documents,
+        snapshots.getDocuments(actor),
+      );
+      if (allDocuments.some((document) => document.placementId === id)) {
+        throw new Error(errors.placementInUse);
+      }
+      return placements.delete({ id });
+    },
+  };
+
+  const documentResource: AdminResource<
+    TDocument,
+    TDocumentDraft,
+    TDocumentDraft,
+    IndexInput
+  > = {
+    getIndex: (input) => documents.getIndex(input),
+    getDetail: (input) => documents.getDetail(input),
+    async create(input, actor) {
+      requireWriteAccess(actor);
+      const draft = parseDocumentDraft(input);
+      const [allDocuments, placement] = await Promise.all([
+        loadAll(documents, snapshots.getDocuments(actor)),
+        findPlacement(
+          placements,
+          draft.placementId,
+          snapshots.getPlacements(actor),
+        ),
+      ]);
+      assertDocumentReferences(
+        placement,
+        allDocuments,
+        draft,
+        errors,
+        rootPlacementKey,
+        assertRootSlug,
+      );
+      const siblings = allDocuments.filter(
+        (document) => document.placementId === draft.placementId,
+      );
+      const position = Math.min(draft.order, siblings.length + 1);
+      return documents.createOrdered({
+        value: { ...draft, order: position },
+        orders: changedOrders(allDocuments, insertOrders(siblings, position)),
+      });
+    },
+    async update({ id, value }, actor) {
+      requireWriteAccess(actor);
+      const draft = parseDocumentDraft(value);
+      const allDocuments = await loadAll(
+        documents,
+        snapshots.getDocuments(actor),
+      );
+      const current = allDocuments.find((document) => document.id === id);
+      if (!current) throw new Error(errors.documentNotFound);
+      const placement = await findPlacement(
+        placements,
+        draft.placementId,
+        snapshots.getPlacements(actor),
+      );
+      assertDocumentReferences(
+        placement,
+        allDocuments,
+        draft,
+        errors,
+        rootPlacementKey,
+        assertRootSlug,
+        id,
+      );
+      const previousSiblings = allDocuments.filter(
+        (document) =>
+          document.id !== id && document.placementId === current.placementId,
+      );
+      const nextSiblings = allDocuments.filter(
+        (document) =>
+          document.id !== id && document.placementId === draft.placementId,
+      );
+      const position = Math.min(draft.order, nextSiblings.length + 1);
+      const valueWithOrder = { ...draft, order: position };
+      const orders =
+        current.placementId === draft.placementId
+          ? insertOrders(nextSiblings, position)
+          : [
+              ...normalizeOrders(previousSiblings),
+              ...insertOrders(nextSiblings, position),
+            ];
+      const updates = changedOrders(allDocuments, orders).filter(
+        (order) => order.id !== id,
+      );
+      if (sameDocument(current, valueWithOrder) && updates.length === 0) {
+        return current;
+      }
+      return documents.updateOrdered({
+        id,
+        value: valueWithOrder,
+        orders: updates,
+      });
+    },
+    async delete({ id }, actor) {
+      requireWriteAccess(actor);
+      const allDocuments = await loadAll(
+        documents,
+        snapshots.getDocuments(actor),
+      );
+      const current = allDocuments.find((document) => document.id === id);
+      if (!current) return;
+      const siblings = allDocuments.filter(
+        (document) =>
+          document.id !== id && document.placementId === current.placementId,
+      );
+      await documents.deleteOrdered({
+        id,
+        orders: changedOrders(allDocuments, normalizeOrders(siblings)),
+      });
+    },
+  };
+
+  return {
+    documents: documentResource,
+    placements: placementResource,
+  } as const;
+}
+
+export async function loadAdminIndex<T>(
+  repository: {
+    getIndex(input?: IndexInput): Promise<{
+      items: readonly T[];
+      nextCursor?: string;
+    }>;
+  },
+  cached?: readonly T[] | null,
+): Promise<T[]> {
+  return loadAll(repository, cached);
+}
+
+function assertUniquePlacementKey(
+  placements: readonly ContentPlacement[],
+  key: string,
+  errors: ContentAdminErrors,
+  exceptId?: string,
+): void {
+  if (placements.some((item) => item.id !== exceptId && item.key === key)) {
+    throw new Error(errors.placementKeyExists);
+  }
+}
+
+function assertDocumentReferences<
+  TPlacement extends ContentPlacement,
+  TDocument extends ContentDocument,
+>(
+  placement: TPlacement | null,
+  documents: readonly TDocument[],
+  draft: ContentDocumentDraft,
+  errors: ContentAdminErrors,
+  rootPlacementKey?: string,
+  assertRootSlug?: (slug: string) => void,
+  exceptId?: string,
+): void {
+  if (!placement) throw new Error(errors.placementNotFound);
+  if (rootPlacementKey && placement.key === rootPlacementKey) {
+    assertRootSlug?.(draft.slug);
+  }
+  if (
+    documents.some(
+      (document) => document.id !== exceptId && document.slug === draft.slug,
+    )
+  ) {
+    throw new Error(errors.documentSlugExists);
+  }
+}
+
+function findPlacement<TPlacement extends ContentPlacement>(
+  repository: { getDetail(input: { id: string }): Promise<TPlacement | null> },
+  id: string,
+  cached: readonly TPlacement[] | null,
+): Promise<TPlacement | null> {
+  const placement = cached?.find((candidate) => candidate.id === id);
+  return placement ? Promise.resolve(placement) : repository.getDetail({ id });
+}
+
+function insertOrders(
+  siblings: readonly ContentDocument[],
+  position: number,
+): ContentOrder[] {
+  return [...siblings]
+    .sort((left, right) => left.order - right.order)
+    .map((document, index) => ({
+      id: document.id,
+      order: index + 1 >= position ? index + 2 : index + 1,
+    }));
+}
+
+function normalizeOrders(
+  documents: readonly ContentDocument[],
+): ContentOrder[] {
+  return [...documents]
+    .sort((left, right) => left.order - right.order)
+    .map((document, index) => ({ id: document.id, order: index + 1 }));
+}
+
+function changedOrders(
+  documents: readonly ContentDocument[],
+  orders: readonly ContentOrder[],
+): ContentOrder[] {
+  const current = new Map(
+    documents.map((document) => [document.id, document.order]),
+  );
+  return orders.filter((order) => current.get(order.id) !== order.order);
+}
+
+function samePlacement(
+  placement: ContentPlacement,
+  draft: ContentPlacementDraft,
+): boolean {
+  return placement.key === draft.key && placement.title === draft.title;
+}
+
+function sameDocument(
+  document: ContentDocument,
+  draft: ContentDocumentDraft,
+): boolean {
+  return (
+    document.content === draft.content &&
+    document.order === draft.order &&
+    document.placementId === draft.placementId &&
+    document.slug === draft.slug &&
+    document.summary === draft.summary &&
+    document.title === draft.title &&
+    document.visibility === draft.visibility
+  );
+}
+
+async function loadAll<T>(
+  repository: {
+    getIndex(input?: IndexInput): Promise<{
+      items: readonly T[];
+      nextCursor?: string;
+    }>;
+  },
+  cached?: readonly T[] | null,
+): Promise<T[]> {
+  if (cached) return [...cached];
+  const items: T[] = [];
+  let cursor: string | undefined;
+  do {
+    const page = await repository.getIndex({ cursor, limit: 100 });
+    items.push(...page.items);
+    cursor = page.nextCursor;
+  } while (cursor);
+  return items;
+}

package/src/content/cache.ts

@@ -0,0 +1,177 @@
+import { createAdminResourceCache } from '../admin';
+import type { ContentDocument, ContentPlacement } from './contracts';
+
+type StoredDocument<TDocument extends ContentDocument> = Omit<
+  TDocument,
+  'updatedAt'
+> & { updatedAt: number };
+
+export function createContentAdminCaches<
+  TPlacement extends ContentPlacement,
+  TDocument extends ContentDocument,
+>({ namespace }: { namespace: string }) {
+  const placementCache = createAdminResourceCache<TPlacement, TPlacement>({
+    collectionKey: `${namespace}:placements`,
+    editorKey: `${namespace}:placement-editor`,
+    getKey: (placement) => placement.id,
+    serializer: {
+      parse(value) {
+        if (!value || typeof value !== 'object') return null;
+        const placement = value as Partial<TPlacement>;
+        return typeof placement.id === 'string' &&
+          typeof placement.key === 'string' &&
+          typeof placement.title === 'string'
+          ? (placement as TPlacement)
+          : null;
+      },
+      serialize: (placement) => placement,
+    },
+    sort: (items) =>
+      [...items].sort((left, right) => left.key.localeCompare(right.key)),
+  });
+  const documentCache = createAdminResourceCache<
+    TDocument,
+    StoredDocument<TDocument>
+  >({
+    collectionKey: `${namespace}:documents`,
+    editorKey: `${namespace}:document-editor`,
+    getKey: (document) => document.id,
+    serializer: {
+      parse(value) {
+        if (!value || typeof value !== 'object') return null;
+        const document = value as Partial<StoredDocument<TDocument>>;
+        if (
+          typeof document.id !== 'string' ||
+          typeof document.placementId !== 'string' ||
+          typeof document.slug !== 'string' ||
+          typeof document.order !== 'number' ||
+          typeof document.updatedAt !== 'number' ||
+          typeof document.title !== 'string' ||
+          typeof document.content !== 'string' ||
+          (document.summary !== undefined &&
+            typeof document.summary !== 'string') ||
+          (document.visibility !== 'private' &&
+            document.visibility !== 'public')
+        ) {
+          return null;
+        }
+        const updatedAt = new Date(document.updatedAt);
+        return Number.isNaN(updatedAt.getTime())
+          ? null
+          : ({ ...document, updatedAt } as unknown as TDocument);
+      },
+      serialize: (document) => ({
+        ...document,
+        updatedAt: document.updatedAt.getTime(),
+      }),
+    },
+    sort: (items) =>
+      [...items].sort(
+        (left, right) =>
+          left.placementId.localeCompare(right.placementId) ||
+          left.order - right.order ||
+          left.title.localeCompare(right.title),
+      ),
+  });
+
+  const readCompletePlacements = (
+    actorId: string,
+  ): readonly TPlacement[] | null => {
+    const page = placementCache.read(actorId, {
+      limit: Number.MAX_SAFE_INTEGER,
+    });
+    return page && !page.nextCursor ? page.items : null;
+  };
+  const readCompleteDocuments = (
+    actorId: string,
+  ): readonly TDocument[] | null => {
+    const page = documentCache.read(actorId, {
+      limit: Number.MAX_SAFE_INTEGER,
+    });
+    return page && !page.nextCursor ? page.items : null;
+  };
+
+  const syncDocumentAfterWrite = (
+    actorId: string,
+    document: TDocument,
+  ): void => {
+    const cached = readCompleteDocuments(actorId);
+    if (!cached) {
+      documentCache.clear(actorId);
+      return;
+    }
+    const previous = cached.find((candidate) => candidate.id === document.id);
+    const placementIds = new Set([
+      document.placementId,
+      ...(previous ? [previous.placementId] : []),
+    ]);
+    const untouched = cached.filter(
+      (candidate) =>
+        candidate.id !== document.id &&
+        !placementIds.has(candidate.placementId),
+    );
+    const updated: TDocument[] = [];
+    for (const placementId of placementIds) {
+      const siblings = cached
+        .filter(
+          (candidate) =>
+            candidate.id !== document.id &&
+            candidate.placementId === placementId,
+        )
+        .toSorted(compareDocumentOrder);
+      if (placementId === document.placementId) {
+        const position = Math.min(
+          Math.max(document.order, 1),
+          siblings.length + 1,
+        );
+        siblings.splice(position - 1, 0, { ...document, order: position });
+      }
+      updated.push(
+        ...siblings.map((candidate, index) => ({
+          ...candidate,
+          order: index + 1,
+        })),
+      );
+    }
+    documentCache.write(actorId, { items: [...untouched, ...updated] });
+  };
+
+  const syncDocumentAfterDelete = (actorId: string, id: string): void => {
+    const cached = readCompleteDocuments(actorId);
+    if (!cached) {
+      documentCache.clear(actorId);
+      return;
+    }
+    const deleted = cached.find((candidate) => candidate.id === id);
+    if (!deleted) return;
+    const items = cached.filter((candidate) => candidate.id !== id);
+    const siblings = items
+      .filter((candidate) => candidate.placementId === deleted.placementId)
+      .toSorted(compareDocumentOrder)
+      .map((candidate, index) => ({ ...candidate, order: index + 1 }));
+    documentCache.write(actorId, {
+      items: [
+        ...items.filter(
+          (candidate) => candidate.placementId !== deleted.placementId,
+        ),
+        ...siblings,
+      ],
+    });
+  };
+
+  return {
+    documentCache,
+    placementCache,
+    readCompleteDocuments,
+    readCompletePlacements,
+    syncDocumentAfterDelete,
+    syncDocumentAfterWrite,
+  } as const;
+}
+
+function compareDocumentOrder(
+  left: ContentDocument,
+  right: ContentDocument,
+): number {
+  return left.order - right.order || left.title.localeCompare(right.title);
+}

package/src/content/catalog.ts

@@ -0,0 +1,72 @@
+import type {
+  ContentDocument,
+  ContentPlacement,
+  ContentSnapshot,
+} from './contracts';
+
+export type ContentCatalog<
+  TPlacement extends ContentPlacement,
+  TDocument extends ContentDocument,
+> = {
+  placements: readonly TPlacement[];
+  placementsById: ReadonlyMap<string, TPlacement>;
+  documents: readonly TDocument[];
+  documentsBySlug: ReadonlyMap<string, TDocument>;
+};
+
+export function createContentCatalog<
+  TPlacement extends ContentPlacement,
+  TDocument extends ContentDocument,
+>(
+  snapshot: ContentSnapshot<TPlacement, TDocument>,
+): ContentCatalog<TPlacement, TDocument> {
+  const placements = [...snapshot.placements].sort((left, right) =>
+    left.title.localeCompare(right.title, 'en'),
+  );
+  const placementsById = new Map(
+    placements.map((placement) => [placement.id, placement]),
+  );
+  const documents = snapshot.documents.toSorted(
+    (left, right) =>
+      left.order - right.order || left.title.localeCompare(right.title, 'en'),
+  );
+
+  for (const document of documents) {
+    if (!placementsById.has(document.placementId)) {
+      throw new Error(`Unknown content placement: ${document.placementId}`);
+    }
+  }
+  assertUnique(
+    placements.map((placement) => placement.key),
+    'content placement key',
+  );
+  assertUnique(
+    documents.map((document) => document.slug),
+    'content document slug',
+  );
+  for (const placement of placements) {
+    assertUnique(
+      documents
+        .filter((document) => document.placementId === placement.id)
+        .map((document) => String(document.order)),
+      `content document order in placement ${placement.key}`,
+    );
+  }
+
+  return {
+    placements,
+    placementsById,
+    documents,
+    documentsBySlug: new Map(
+      documents.map((document) => [document.slug, document]),
+    ),
+  };
+}
+
+function assertUnique(values: readonly string[], label: string): void {
+  const seen = new Set<string>();
+  for (const value of values) {
+    if (seen.has(value)) throw new Error(`Duplicate ${label}: ${value}`);
+    seen.add(value);
+  }
+}

package/src/content/contracts.ts

@@ -0,0 +1,77 @@
+import type { AdminPage } from '../admin';
+
+export type ContentVisibility = 'public' | 'private';
+
+export type ContentPlacement = {
+  id: string;
+  key: string;
+  title: string;
+};
+
+export type ContentDocument = {
+  content: string;
+  id: string;
+  order: number;
+  placementId: string;
+  slug: string;
+  summary?: string;
+  title: string;
+  updatedAt: Date;
+  visibility: ContentVisibility;
+};
+
+export type ContentSnapshot<
+  TPlacement extends ContentPlacement = ContentPlacement,
+  TDocument extends ContentDocument = ContentDocument,
+> = {
+  placements: readonly TPlacement[];
+  documents: readonly TDocument[];
+  updatedAt: Date | null;
+};
+
+export type ContentPlacementDraft = Pick<ContentPlacement, 'key' | 'title'>;
+
+export type ContentDocumentDraft = Omit<ContentDocument, 'id' | 'updatedAt'>;
+
+export interface ContentPlacementAdminRepository<
+  TPlacement extends ContentPlacement,
+  TPlacementDraft extends ContentPlacementDraft,
+> {
+  getIndex(input?: {
+    cursor?: string;
+    limit?: number;
+  }): Promise<AdminPage<TPlacement>>;
+  getDetail(input: { id: string }): Promise<TPlacement | null>;
+  create(input: TPlacementDraft): Promise<TPlacement>;
+  update(input: { id: string; value: TPlacementDraft }): Promise<TPlacement>;
+  delete(input: { id: string }): Promise<void>;
+}
+
+export interface ContentDocumentAdminRepository<
+  TDocument extends ContentDocument,
+  TDocumentDraft extends ContentDocumentDraft,
+> {
+  getIndex(input?: {
+    cursor?: string;
+    limit?: number;
+  }): Promise<AdminPage<TDocument>>;
+  getDetail(input: { id: string }): Promise<TDocument | null>;
+  create(input: TDocumentDraft): Promise<TDocument>;
+  update(input: { id: string; value: TDocumentDraft }): Promise<TDocument>;
+  delete(input: { id: string }): Promise<void>;
+  createOrdered(input: {
+    value: TDocumentDraft;
+    orders: readonly ContentOrder[];
+  }): Promise<TDocument>;
+  updateOrdered(input: {
+    id: string;
+    value: TDocumentDraft;
+    orders: readonly ContentOrder[];
+  }): Promise<TDocument>;
+  deleteOrdered(input: {
+    id: string;
+    orders: readonly ContentOrder[];
+  }): Promise<void>;
+}
+
+export type ContentOrder = { id: string; order: number };