@astronox/core 0.2.4 → 0.3.1

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 };

package/src/content/drafts.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+import type { ContentDocumentDraft, ContentPlacementDraft } from './contracts';
+
+export const contentKeySchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(80)
+  .transform((value) =>
+    value
+      .normalize('NFKD')
+      .replace(/[\u0300-\u036f]/g, '')
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, ''),
+  )
+  .pipe(z.string().min(1));
+
+const placementDraftSchema = z.object({
+  key: contentKeySchema,
+  title: z.string().trim().min(1).max(120),
+});
+
+const documentDraftSchema = z.object({
+  placementId: z.string().trim().min(1),
+  content: z.string().trim().min(1).max(200_000),
+  order: z.coerce.number().int().positive(),
+  slug: contentKeySchema,
+  summary: z
+    .string()
+    .trim()
+    .max(500)
+    .optional()
+    .transform((value) => value || undefined),
+  title: z.string().trim().min(1).max(160),
+  visibility: z.enum(['public', 'private']),
+});
+
+export function parseContentPlacementDraft(
+  input: unknown,
+): ContentPlacementDraft {
+  return placementDraftSchema.parse(input);
+}
+
+export function parseContentDocumentDraft(
+  input: unknown,
+): ContentDocumentDraft {
+  return documentDraftSchema.parse(input);
+}

package/src/content/index.ts

@@ -0,0 +1,7 @@
+export * from './admin';
+export * from './cache';
+export * from './catalog';
+export * from './contracts';
+export * from './drafts';
+export * from './markdown';
+export * from './snapshot';

package/src/content/markdown.ts

@@ -0,0 +1,146 @@
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import type {
+  MarkdownBlock,
+  MarkdownDocument,
+  MarkdownHeadingLevel,
+  MarkdownInline,
+} from '../components/content/MarkdownContent/contracts';
+
+type AstNode = {
+  children?: AstNode[];
+  depth?: number;
+  lang?: string;
+  type?: string;
+  url?: string;
+  value?: string;
+};
+
+export function parseMarkdownDocument(source: string): MarkdownDocument {
+  const root = fromMarkdown(source) as AstNode;
+  const headingIds = new Map<string, number>();
+  return {
+    blocks: (root.children ?? []).flatMap((node) => toBlocks(node, headingIds)),
+  };
+}
+
+function toBlocks(
+  node: AstNode,
+  headingIds: Map<string, number>,
+): MarkdownBlock[] {
+  switch (node.type) {
+    case 'paragraph':
+      return [{ type: 'paragraph', children: toInlineChildren(node) }];
+    case 'heading': {
+      const children = toInlineChildren(node);
+      const title = inlineText(children);
+      const level = Math.min(
+        6,
+        Math.max(2, node.depth ?? 2),
+      ) as MarkdownHeadingLevel;
+      return [
+        {
+          type: 'heading',
+          children,
+          id: uniqueSlug(title, headingIds),
+          level,
+        },
+      ];
+    }
+    case 'list':
+      return [
+        {
+          type: 'list',
+          items: (node.children ?? [])
+            .filter((item) => item.type === 'listItem')
+            .map((item) => ({
+              children: (item.children ?? []).flatMap((child) =>
+                toBlocks(child, headingIds),
+              ),
+            })),
+        },
+      ];
+    case 'blockquote':
+      return [
+        {
+          type: 'quote',
+          children: (node.children ?? []).flatMap((child) =>
+            toBlocks(child, headingIds),
+          ),
+        },
+      ];
+    case 'code':
+      return [
+        {
+          type: 'code',
+          language: node.lang,
+          value: node.value ?? '',
+        },
+      ];
+    case 'thematicBreak':
+      return [{ type: 'separator' }];
+    default:
+      return [];
+  }
+}
+
+function toInlineChildren(node: AstNode): MarkdownInline[] {
+  return (node.children ?? []).flatMap(toInline);
+}
+
+function toInline(node: AstNode): MarkdownInline[] {
+  switch (node.type) {
+    case 'text':
+      return [{ type: 'text', value: node.value ?? '' }];
+    case 'strong':
+      return [{ type: 'strong', children: toInlineChildren(node) }];
+    case 'emphasis':
+      return [{ type: 'emphasis', children: toInlineChildren(node) }];
+    case 'inlineCode':
+      return [{ type: 'code', value: node.value ?? '' }];
+    case 'break':
+      return [{ type: 'break' }];
+    case 'link': {
+      const href = node.url ?? '';
+      return [
+        {
+          type: 'link',
+          children: toInlineChildren(node),
+          external: /^(?:https?:)?\/\//i.test(href),
+          href,
+        },
+      ];
+    }
+    default:
+      return [];
+  }
+}
+
+function inlineText(nodes: readonly MarkdownInline[]): string {
+  return nodes
+    .map((node) => {
+      if (node.type === 'text' || node.type === 'code') return node.value;
+      if (
+        node.type === 'strong' ||
+        node.type === 'emphasis' ||
+        node.type === 'link'
+      ) {
+        return inlineText(node.children);
+      }
+      return '';
+    })
+    .join('')
+    .trim();
+}
+
+function uniqueSlug(value: string, counts: Map<string, number>): string {
+  const base =
+    value
+      .normalize('NFKD')
+      .replace(/[\u0300-\u036f]/g, '')
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '') || 'section';
+  const count = counts.get(base) ?? 0;
+  counts.set(base, count + 1);
+  return count === 0 ? base : `${base}-${count + 1}`;
+}

package/src/content/snapshot.ts

@@ -0,0 +1,139 @@
+import type {
+  ContentDocument,
+  ContentPlacement,
+  ContentSnapshot,
+} from './contracts';
+
+type RecordValue = Record<string, unknown>;
+
+export type ContentSnapshotFields = {
+  documents: string;
+  documentPlacementId: string;
+  label: string;
+  placements: string;
+};
+
+export function parseContentSnapshot(
+  value: unknown,
+  fields: ContentSnapshotFields,
+): ContentSnapshot {
+  const source = requireRecord(value, fields.label);
+  const rawPlacements = requireArray(source[fields.placements], fields.label);
+  const rawDocuments = requireArray(source[fields.documents], fields.label);
+  const placements = rawPlacements.map((entry) =>
+    parsePlacement(entry, fields.label),
+  );
+  const documents = rawDocuments.map((entry) =>
+    parseDocument(entry, fields.documentPlacementId, fields.label),
+  );
+  const placementIds = new Set(placements.map((placement) => placement.id));
+
+  for (const document of documents) {
+    if (!placementIds.has(document.placementId)) {
+      throw new Error(
+        `Invalid ${fields.label} document placement: ${document.id}`,
+      );
+    }
+  }
+
+  return {
+    placements,
+    documents,
+    updatedAt:
+      source.updatedAt === undefined || source.updatedAt === null
+        ? null
+        : parseSnapshotDate(source.updatedAt, fields.label),
+  };
+}
+
+export function projectPublicContentSnapshot<
+  TPlacement extends ContentPlacement,
+  TDocument extends ContentDocument,
+>(
+  snapshot: ContentSnapshot<TPlacement, TDocument>,
+): ContentSnapshot<TPlacement, TDocument> {
+  return {
+    ...snapshot,
+    documents: snapshot.documents.filter(
+      (document) => document.visibility === 'public',
+    ),
+  };
+}
+
+export function parseSnapshotDate(value: unknown, label = 'snapshot'): Date {
+  const timestamp = isRecord(value)
+    ? typeof value._seconds === 'number'
+      ? value._seconds * 1_000
+      : typeof value.seconds === 'number'
+        ? value.seconds * 1_000
+        : Number.NaN
+    : value;
+  const date = new Date(timestamp as string | number | Date);
+  if (Number.isNaN(date.getTime())) throw new Error(`Invalid ${label} date`);
+  return date;
+}
+
+function parsePlacement(value: unknown, label: string): ContentPlacement {
+  const source = requireRecord(value, label);
+  return {
+    id: requireString(source.id, label),
+    key: requireString(source.key, label),
+    title: requireString(source.title, label),
+  };
+}
+
+function parseDocument(
+  value: unknown,
+  placementIdField: string,
+  label: string,
+): ContentDocument {
+  const source = requireRecord(value, label);
+  const order =
+    typeof source.order === 'number' ? source.order : Number(source.order);
+  if (!Number.isInteger(order) || order < 1) {
+    throw new Error(`Invalid ${label} document order`);
+  }
+  if (source.private !== undefined && typeof source.private !== 'boolean') {
+    throw new Error(`Invalid ${label} document visibility`);
+  }
+  const summary = readOptionalString(source.summary, label);
+
+  return {
+    content: requireString(source.content, label),
+    id: requireString(source.id, label),
+    order,
+    placementId: requireString(source[placementIdField], label),
+    slug: requireString(source.slug, label),
+    ...(summary ? { summary } : {}),
+    title: requireString(source.title, label),
+    updatedAt: parseSnapshotDate(source.updatedAt, label),
+    visibility: source.private === true ? 'private' : 'public',
+  };
+}
+
+function requireArray(value: unknown, label: string): unknown[] {
+  if (!Array.isArray(value)) throw new Error(`Invalid ${label} snapshot`);
+  return value;
+}
+
+function requireRecord(value: unknown, label: string): RecordValue {
+  if (!isRecord(value)) throw new Error(`Invalid ${label} snapshot`);
+  return value;
+}
+
+function requireString(value: unknown, label: string): string {
+  const resolved = typeof value === 'string' ? value.trim() : '';
+  if (!resolved) throw new Error(`Invalid ${label} snapshot string`);
+  return resolved;
+}
+
+function readOptionalString(value: unknown, label: string): string | undefined {
+  if (value === undefined || value === null || value === '') return undefined;
+  if (typeof value !== 'string')
+    throw new Error(`Invalid ${label} optional string`);
+  return value.trim() || undefined;
+}
+
+function isRecord(value: unknown): value is RecordValue {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/data/firestore/client/contracts.ts

@@ -1,5 +1,7 @@
 import type { Firestore } from 'firebase/firestore';
 
+export type ClientFirestore = Firestore;
+
 export type ClientFirestorePage<TItem> = {
   items: readonly TItem[];
   nextCursor?: string;
@@ -16,11 +18,12 @@ export type ClientFirestoreCursor<TDocument> = {
 };
 
 export type ClientFirestoreDocumentMapper<
+  TDocument,
   TItem,
   TCreateInput,
   TUpdateInput,
 > = {
-  fromDocument(id: string, value: unknown): TItem;
+  fromDocument(id: string, value: TDocument): TItem;
   toCreate(input: TCreateInput): Record<string, unknown>;
   toUpdate(input: TUpdateInput): Record<string, unknown>;
 };
@@ -49,7 +52,12 @@ export type ClientFirestoreRepositoryConfig<
   collection: string;
   cursor?: ClientFirestoreCursor<TDocument>;
   database: Firestore;
-  mapper: ClientFirestoreDocumentMapper<TItem, TCreateInput, TUpdateInput>;
+  mapper: ClientFirestoreDocumentMapper<
+    TDocument,
+    TItem,
+    TCreateInput,
+    TUpdateInput
+  >;
   orderBy?: readonly ClientFirestoreOrder[];
   schema: ClientFirestoreSchema<TDocument>;
 };