@bendyline/squisq 1.3.0 → 1.4.0

package/src/versions/operations.ts

@@ -0,0 +1,230 @@
+/**
+ * Pure-ish version operations against a {@link ContentContainer}.
+ *
+ * These functions are the canonical implementation. {@link DocumentVersionManager}
+ * is a thin wrapper that captures a container reference for ergonomics.
+ */
+
+import type { ContentContainer } from '../storage/ContentContainer.js';
+import { buildVersionPath, getDocBasename, parseVersionPath, VERSIONS_PREFIX } from './paths.js';
+import type {
+  CoalesceOptions,
+  PrunePolicy,
+  RevertOptions,
+  SaveVersionOptions,
+  SaveVersionResult,
+  Version,
+} from './types.js';
+
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+
+async function resolveBasename(
+  container: ContentContainer,
+  override: string | undefined,
+): Promise<string | null> {
+  if (override) return override;
+  const docPath = await container.getDocumentPath();
+  if (!docPath) return null;
+  return getDocBasename(docPath);
+}
+
+async function resolveDocPath(container: ContentContainer): Promise<string> {
+  // Default to `index.md` when the container has no document yet — matches
+  // `MemoryContentContainer.writeDocument`'s default.
+  const docPath = await container.getDocumentPath();
+  return docPath ?? 'index.md';
+}
+
+/**
+ * List all snapshots in the container, newest-first.
+ *
+ * @param basename Optional filter: when set, only versions whose basename
+ *   matches are returned.
+ */
+export async function listVersions(
+  container: ContentContainer,
+  basename?: string,
+): Promise<Version[]> {
+  const entries = await container.listFiles(VERSIONS_PREFIX);
+  const versions: Version[] = [];
+  for (const entry of entries) {
+    const parsed = parseVersionPath(entry.path);
+    if (!parsed) continue;
+    if (basename !== undefined && parsed.basename !== basename) continue;
+    versions.push({
+      path: entry.path,
+      basename: parsed.basename,
+      timestamp: parsed.timestamp,
+      size: entry.size,
+      collision: parsed.collision,
+    });
+  }
+  // Newest first. Tie-break on collision (higher = newer). Compare the
+  // numeric collision rather than the path string: lexicographically a path
+  // with no suffix sorts *after* one with `-N`, because `.` (0x2E) is
+  // greater than `-` (0x2D), which would invert the order.
+  versions.sort((a, b) => {
+    const dt = b.timestamp.getTime() - a.timestamp.getTime();
+    if (dt !== 0) return dt;
+    return b.collision - a.collision;
+  });
+  return versions;
+}
+
+/**
+ * Read the markdown content of a snapshot. Returns null if the snapshot
+ * doesn't exist.
+ */
+export async function readVersion(
+  container: ContentContainer,
+  version: Version | string,
+): Promise<string | null> {
+  const path = typeof version === 'string' ? version : version.path;
+  const data = await container.readFile(path);
+  if (!data) return null;
+  return decoder.decode(data);
+}
+
+/**
+ * Save a new snapshot of the document if its content differs from the
+ * latest existing snapshot.
+ */
+export async function saveVersion(
+  container: ContentContainer,
+  options: SaveVersionOptions = {},
+): Promise<SaveVersionResult> {
+  const content = options.content ?? (await container.readDocument());
+  if (content === null || content === undefined) {
+    return { saved: false, version: null, reason: 'no-document' };
+  }
+  if (content.length === 0) {
+    return { saved: false, version: null, reason: 'empty' };
+  }
+
+  const basename = await resolveBasename(container, options.basename);
+  if (!basename) {
+    return { saved: false, version: null, reason: 'no-document' };
+  }
+
+  const versions = await listVersions(container, basename);
+  if (!options.force && versions.length > 0) {
+    const latest = versions[0]!;
+    const existing = await readVersion(container, latest);
+    if (existing === content) {
+      return { saved: false, version: null, reason: 'unchanged' };
+    }
+  }
+
+  const now = options.now ?? new Date();
+  let collision = 0;
+  let path = buildVersionPath(basename, now, collision);
+  while (await container.exists(path)) {
+    collision += 1;
+    path = buildVersionPath(basename, now, collision);
+  }
+
+  const data = encoder.encode(content);
+  await container.writeFile(path, data, 'text/markdown');
+
+  const version: Version = {
+    path,
+    basename,
+    timestamp: now,
+    size: data.byteLength,
+    collision,
+  };
+  return { saved: true, version, reason: 'saved' };
+}
+
+/**
+ * Revert the document to a prior snapshot. By default, the *current*
+ * document is snapshotted first so the revert is itself recoverable.
+ */
+export async function revertToVersion(
+  container: ContentContainer,
+  version: Version | string,
+  options: RevertOptions = {},
+): Promise<{ reverted: boolean; snapshotted: Version | null }> {
+  const content = await readVersion(container, version);
+  if (content === null) {
+    return { reverted: false, snapshotted: null };
+  }
+
+  let snapshotted: Version | null = null;
+  if (options.snapshotCurrent !== false) {
+    const result = await saveVersion(container);
+    snapshotted = result.version;
+  }
+
+  const docPath = await resolveDocPath(container);
+  await container.writeDocument(content, docPath);
+  return { reverted: true, snapshotted };
+}
+
+/**
+ * Delete snapshots that don't satisfy the policy. Returns the deleted
+ * versions in their original (newest-first) order.
+ */
+export async function pruneVersions(
+  container: ContentContainer,
+  policy: PrunePolicy,
+  basename?: string,
+): Promise<Version[]> {
+  const versions = await listVersions(container, basename);
+  const toDelete: Version[] = [];
+
+  if (policy.type === 'keep-last-n') {
+    const n = Math.max(0, Math.floor(policy.n));
+    toDelete.push(...versions.slice(n));
+  } else if (policy.type === 'older-than') {
+    const cutoff = policy.date.getTime();
+    for (const v of versions) {
+      if (v.timestamp.getTime() < cutoff) toDelete.push(v);
+    }
+  } else {
+    for (const v of versions) {
+      if (!policy.keep(v, versions)) toDelete.push(v);
+    }
+  }
+
+  for (const v of toDelete) {
+    await container.removeFile(v.path);
+  }
+  return toDelete;
+}
+
+/**
+ * Collapse adjacent snapshots that occurred close together — keeping the
+ * newer one — to keep history readable across rapid edits.
+ */
+export async function coalesceVersions(
+  container: ContentContainer,
+  options: CoalesceOptions = {},
+  basename?: string,
+): Promise<Version[]> {
+  const windowMs = options.windowMs ?? 60_000;
+  const versions = await listVersions(container, basename);
+  const toDelete: Version[] = [];
+  // Walk newest -> oldest, anchored to the last *kept* snapshot. Any
+  // candidate within `windowMs` of the anchor is dropped; the first one
+  // outside the window becomes the new anchor. Comparing each pair against
+  // its previous neighbor instead would chain through deleted snapshots
+  // and over-prune any tightly-clustered run (e.g. 30s apart with a 60s
+  // window collapses to a single survivor).
+  if (versions.length > 0) {
+    let anchor = versions[0]!;
+    for (let i = 1; i < versions.length; i++) {
+      const candidate = versions[i]!;
+      if (anchor.timestamp.getTime() - candidate.timestamp.getTime() <= windowMs) {
+        toDelete.push(candidate);
+      } else {
+        anchor = candidate;
+      }
+    }
+  }
+  for (const v of toDelete) {
+    await container.removeFile(v.path);
+  }
+  return toDelete;
+}

package/src/versions/paths.ts

@@ -0,0 +1,66 @@
+/**
+ * Path conventions for version snapshots.
+ *
+ * Snapshots live at `<VERSIONS_PREFIX><basename>.<timestamp>[<-suffix>].md`.
+ * The optional numeric suffix (`-2`, `-3`, ...) is appended only when two
+ * snapshots collide on the same UTC second.
+ */
+
+import { formatVersionTimestamp, parseVersionTimestamp } from './timestamp.js';
+
+/** Subfolder (inside the ContentContainer) that holds version snapshots. */
+export const VERSIONS_PREFIX = '.versions/';
+
+/**
+ * Strip the directory and extension from a document path to produce the
+ * basename used in version filenames. `subdir/index.md` -> `index`.
+ */
+export function getDocBasename(documentPath: string): string {
+  const slash = documentPath.lastIndexOf('/');
+  const file = slash >= 0 ? documentPath.slice(slash + 1) : documentPath;
+  const dot = file.lastIndexOf('.');
+  return dot > 0 ? file.slice(0, dot) : file;
+}
+
+/**
+ * Build a version snapshot path. Optionally append a collision suffix
+ * (e.g. `2`, `3`) when two saves land on the same UTC second.
+ */
+export function buildVersionPath(basename: string, date: Date, collision = 0): string {
+  const stamp = formatVersionTimestamp(date);
+  const suffix = collision > 0 ? `-${collision + 1}` : '';
+  return `${VERSIONS_PREFIX}${basename}.${stamp}${suffix}.md`;
+}
+
+/**
+ * Parse a version snapshot path. Returns null if it doesn't match the
+ * convention (so unrelated files stored under `.versions/` are ignored).
+ */
+export function parseVersionPath(
+  path: string,
+): { basename: string; timestamp: Date; collision: number } | null {
+  if (!path.startsWith(VERSIONS_PREFIX)) return null;
+  const rest = path.slice(VERSIONS_PREFIX.length);
+  if (!rest.endsWith('.md')) return null;
+  const stem = rest.slice(0, -'.md'.length);
+  // basename can contain dots; the timestamp is always the *last* dot-segment
+  // (optionally followed by a `-N` collision suffix).
+  const lastDot = stem.lastIndexOf('.');
+  if (lastDot <= 0) return null;
+  const basename = stem.slice(0, lastDot);
+  const tail = stem.slice(lastDot + 1);
+  const dash = tail.indexOf('-');
+  let stamp: string;
+  let collision = 0;
+  if (dash >= 0) {
+    stamp = tail.slice(0, dash);
+    const n = Number(tail.slice(dash + 1));
+    if (!Number.isInteger(n) || n < 2) return null;
+    collision = n - 1;
+  } else {
+    stamp = tail;
+  }
+  const timestamp = parseVersionTimestamp(stamp);
+  if (!timestamp) return null;
+  return { basename, timestamp, collision };
+}

package/src/versions/timestamp.ts

@@ -0,0 +1,48 @@
+/**
+ * Sortable, human-readable timestamps for version filenames.
+ *
+ * Format: ISO 8601 basic, UTC, second precision, `Z` suffix —
+ * e.g. `20260430T152030Z`. Lexicographic order matches chronological order,
+ * so `listFiles` returns versions in time order without parsing.
+ */
+
+const TIMESTAMP_RE = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/;
+
+function pad2(n: number): string {
+  return n < 10 ? `0${n}` : String(n);
+}
+
+/**
+ * Format a Date as a sortable, filename-safe UTC timestamp string.
+ */
+export function formatVersionTimestamp(date: Date): string {
+  return (
+    String(date.getUTCFullYear()).padStart(4, '0') +
+    pad2(date.getUTCMonth() + 1) +
+    pad2(date.getUTCDate()) +
+    'T' +
+    pad2(date.getUTCHours()) +
+    pad2(date.getUTCMinutes()) +
+    pad2(date.getUTCSeconds()) +
+    'Z'
+  );
+}
+
+/**
+ * Parse a version timestamp string back to a Date. Returns null if the input
+ * doesn't match the expected format.
+ */
+export function parseVersionTimestamp(stamp: string): Date | null {
+  const m = TIMESTAMP_RE.exec(stamp);
+  if (!m) return null;
+  const [, y, mo, d, h, mi, s] = m;
+  const ms = Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s));
+  if (Number.isNaN(ms)) return null;
+  return new Date(ms);
+}
+
+/**
+ * The pattern a valid version timestamp matches. Exported so other modules
+ * can validate filenames without re-deriving the regex.
+ */
+export const VERSION_TIMESTAMP_PATTERN = TIMESTAMP_RE;

package/src/versions/types.ts

@@ -0,0 +1,91 @@
+/**
+ * Public types for the document version-history feature.
+ *
+ * Versions are snapshots of the primary markdown document stored alongside
+ * the document inside the same {@link ContentContainer}. They live under
+ * `.versions/<docBasename>.<sortableTimestamp>.md`. The container is the
+ * unit of persistence — when the host serializes the container to a ZIP,
+ * a real folder, or anywhere else, the version snapshots ride along.
+ */
+
+/**
+ * A single version snapshot record.
+ */
+export interface Version {
+  /** Container-relative path, e.g. `.versions/index.20260430T152030Z.md`. */
+  path: string;
+  /** Document basename without extension, e.g. `index`. */
+  basename: string;
+  /** Parsed timestamp from the filename, in UTC. */
+  timestamp: Date;
+  /** Snapshot size in bytes. */
+  size: number;
+  /**
+   * Collision suffix index. `0` for a path with no `-N` suffix, `1` for `-2`,
+   * `2` for `-3`, and so on. Used as the tie-break for ordering snapshots
+   * that share the same UTC second.
+   */
+  collision: number;
+}
+
+/**
+ * Result of a {@link saveVersion} call.
+ */
+export interface SaveVersionResult {
+  /** True when a new snapshot file was actually written. */
+  saved: boolean;
+  /** The newly stamped version (only when `saved` is true). */
+  version: Version | null;
+  /**
+   * Why the save behaved the way it did:
+   * - `'saved'`        — a new snapshot was written.
+   * - `'unchanged'`    — current content matches the latest snapshot byte-for-byte.
+   * - `'no-document'`  — the container has no primary markdown document.
+   * - `'empty'`        — the resolved content was empty.
+   */
+  reason: 'saved' | 'unchanged' | 'no-document' | 'empty';
+}
+
+/**
+ * Options for {@link saveVersion}.
+ */
+export interface SaveVersionOptions {
+  /** Override the document content; otherwise the container's primary doc is read. */
+  content?: string;
+  /** Override the timestamp; defaults to `new Date()`. Useful for tests. */
+  now?: Date;
+  /** Skip the diff-vs-latest check and force a write. */
+  force?: boolean;
+  /** Override the document basename used to build the version filename. */
+  basename?: string;
+}
+
+/**
+ * Pruning policy passed to {@link pruneVersions}.
+ */
+export type PrunePolicy =
+  | { type: 'keep-last-n'; n: number }
+  | { type: 'older-than'; date: Date }
+  | { type: 'predicate'; keep: (v: Version, all: Version[]) => boolean };
+
+/**
+ * Options for {@link revertToVersion}.
+ */
+export interface RevertOptions {
+  /**
+   * Whether to snapshot the current document content before replacing it.
+   * Defaults to `true` so a revert is always recoverable.
+   */
+  snapshotCurrent?: boolean;
+}
+
+/**
+ * Options for {@link coalesceVersions}.
+ */
+export interface CoalesceOptions {
+  /**
+   * Two adjacent snapshots whose timestamps are within `windowMs` collapse
+   * to the newer one. Defaults to 60_000 (one minute).
+   */
+  windowMs?: number;
+}