@bendyline/squisq 2.1.0 → 2.2.0

package/src/versions/snapshotStore.ts

@@ -1,202 +0,0 @@
-/**
- * Internal storage engine shared by document and image-editor histories.
- * Public APIs keep their domain-specific names and result reasons; this module
- * owns the mechanics that must behave identically across both histories.
- */
-
-import type { ContentContainer } from '../storage/ContentContainer.js';
-import { ensureVersionsGitIgnored } from './gitignore.js';
-import { formatVersionTimestamp, parseVersionTimestamp } from './timestamp.js';
-import type { CoalesceOptions, PrunePolicy, Version } from './types.js';
-
-const decoder = new TextDecoder();
-const encoder = new TextEncoder();
-
-export interface SnapshotPathStrategy {
-  readonly prefix: string;
-  readonly extension: string;
-}
-
-export interface SaveTextSnapshotOptions {
-  content: string;
-  basename: string;
-  mimeType: string;
-  now?: Date;
-  force?: boolean;
-}
-
-export interface SaveTextSnapshotResult {
-  saved: boolean;
-  version: Version | null;
-  reason: 'saved' | 'unchanged';
-}
-
-export function buildSnapshotPath(
-  strategy: SnapshotPathStrategy,
-  basename: string,
-  date: Date,
-  collision = 0,
-): string {
-  const stamp = formatVersionTimestamp(date);
-  const suffix = collision > 0 ? `-${collision + 1}` : '';
-  return `${strategy.prefix}${basename}.${stamp}${suffix}.${strategy.extension}`;
-}
-
-export function parseSnapshotPath(
-  strategy: SnapshotPathStrategy,
-  path: string,
-): { basename: string; timestamp: Date; collision: number } | null {
-  if (!path.startsWith(strategy.prefix)) return null;
-  const extension = `.${strategy.extension}`;
-  const rest = path.slice(strategy.prefix.length);
-  if (!rest.endsWith(extension)) return null;
-  const stem = rest.slice(0, -extension.length);
-  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 = tail;
-  let collision = 0;
-  if (dash >= 0) {
-    stamp = tail.slice(0, dash);
-    const suffix = Number(tail.slice(dash + 1));
-    if (!Number.isInteger(suffix) || suffix < 2) return null;
-    collision = suffix - 1;
-  }
-
-  const timestamp = parseVersionTimestamp(stamp);
-  return timestamp ? { basename, timestamp, collision } : null;
-}
-
-export async function listSnapshots(
-  container: ContentContainer,
-  strategy: SnapshotPathStrategy,
-  basename?: string,
-): Promise<Version[]> {
-  const entries = await container.listFiles(strategy.prefix);
-  const versions: Version[] = [];
-  for (const entry of entries) {
-    const parsed = parseSnapshotPath(strategy, entry.path);
-    if (!parsed || (basename !== undefined && parsed.basename !== basename)) continue;
-    versions.push({
-      path: entry.path,
-      basename: parsed.basename,
-      timestamp: parsed.timestamp,
-      size: entry.size,
-      collision: parsed.collision,
-    });
-  }
-
-  versions.sort((a, b) => {
-    const timestampDelta = b.timestamp.getTime() - a.timestamp.getTime();
-    return timestampDelta || b.collision - a.collision;
-  });
-  return versions;
-}
-
-export async function readTextSnapshot(
-  container: ContentContainer,
-  version: Version | string,
-): Promise<string | null> {
-  const path = typeof version === 'string' ? version : version.path;
-  const data = await container.readFile(path);
-  return data ? decoder.decode(data) : null;
-}
-
-export async function saveTextSnapshot(
-  container: ContentContainer,
-  strategy: SnapshotPathStrategy,
-  options: SaveTextSnapshotOptions,
-): Promise<SaveTextSnapshotResult> {
-  const versions = await listSnapshots(container, strategy, options.basename);
-  if (!options.force && versions.length > 0) {
-    const existing = await readTextSnapshot(container, versions[0]!);
-    if (existing === options.content) {
-      // Backfill containers written before history owned its ignore rule.
-      await ensureVersionsGitIgnored(container);
-      return { saved: false, version: null, reason: 'unchanged' };
-    }
-  }
-
-  const now = options.now ?? new Date();
-  let collision = 0;
-  let path = buildSnapshotPath(strategy, options.basename, now, collision);
-  while (await container.exists(path)) {
-    collision += 1;
-    path = buildSnapshotPath(strategy, options.basename, now, collision);
-  }
-
-  const data = encoder.encode(options.content);
-  await ensureVersionsGitIgnored(container);
-  await container.writeFile(path, data, options.mimeType);
-  return {
-    saved: true,
-    version: {
-      path,
-      basename: options.basename,
-      timestamp: now,
-      size: data.byteLength,
-      collision,
-    },
-    reason: 'saved',
-  };
-}
-
-export async function pruneSnapshots(
-  container: ContentContainer,
-  strategy: SnapshotPathStrategy,
-  policy: PrunePolicy,
-  basename?: string,
-): Promise<Version[]> {
-  const versions = await listSnapshots(container, strategy, basename);
-  let toDelete: Version[];
-
-  if (policy.type === 'keep-last-n') {
-    toDelete = versions.slice(Math.max(0, Math.floor(policy.n)));
-  } else if (policy.type === 'older-than') {
-    const cutoff = policy.date.getTime();
-    toDelete = versions.filter((version) => version.timestamp.getTime() < cutoff);
-  } else {
-    toDelete = versions.filter((version) => !policy.keep(version, versions));
-  }
-
-  await removeSnapshots(container, toDelete);
-  return toDelete;
-}
-
-export async function coalesceSnapshots(
-  container: ContentContainer,
-  strategy: SnapshotPathStrategy,
-  options: CoalesceOptions = {},
-  basename?: string,
-): Promise<Version[]> {
-  const windowMs = options.windowMs ?? 60_000;
-  const versions = await listSnapshots(container, strategy, basename);
-  const toDelete: Version[] = [];
-
-  // Compare against the last kept snapshot. Pairwise comparison against a
-  // deleted neighbor would chain through a dense run and over-prune it.
-  if (versions.length > 0) {
-    let anchor = versions[0]!;
-    for (let index = 1; index < versions.length; index++) {
-      const candidate = versions[index]!;
-      if (anchor.timestamp.getTime() - candidate.timestamp.getTime() <= windowMs) {
-        toDelete.push(candidate);
-      } else {
-        anchor = candidate;
-      }
-    }
-  }
-
-  await removeSnapshots(container, toDelete);
-  return toDelete;
-}
-
-async function removeSnapshots(
-  container: ContentContainer,
-  versions: readonly Version[],
-): Promise<void> {
-  for (const version of versions) await container.removeFile(version.path);
-}

package/src/versions/timestamp.ts

@@ -1,48 +0,0 @@
-/**
- * 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

@@ -1,93 +0,0 @@
-/**
- * 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. When
- * snapshots are retained, a container-root `.gitignore` rule excludes the
- * `.versions/` folder from Git.
- */
-
-/**
- * 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;
-}