Skip to content

Write HTML. Render video. Built for agents.

4.7 KB
Raw Blame
import type { PersistAdapter, PersistVersionEntry } from "./types.js";
import type { PersistErrorEvent } from "../types.js";
import { readFile, writeFile, mkdir, readdir, unlink, stat } from "node:fs/promises";
import { replaceFileAtomically, resolveWritePath } from "@hyperframes/core/atomic-file";
import { join, dirname } from "node:path";

export interface FsAdapterOptions {
  /** Root directory for composition files */
  root: string;
  /** Max versions to keep per file. Default: 20 */
  maxVersions?: number;
}

const DEFAULT_MAX_VERSIONS = 20;

let _versionCounter = 0;

class FsAdapter implements PersistAdapter {
  private readonly root: string;
  private readonly maxVersions: number;
  private errorHandlers: Array<(e: PersistErrorEvent) => void> = [];
  private readonly inflightWrites = new Set<Promise<void>>();
  private _writeLocks = new Map<string, Promise<void>>();

  constructor(opts: FsAdapterOptions) {
    this.root = opts.root;
    this.maxVersions = opts.maxVersions ?? DEFAULT_MAX_VERSIONS;
  }

  async read(path: string): Promise<string | undefined> {
    try {
      return await readFile(this.abs(path), "utf8");
    } catch (err: unknown) {
      if (isNotFound(err)) return undefined;
      throw err;
    }
  }

  async write(path: string, content: string): Promise<void> {
    const p = this.doWrite(path, content);
    this.inflightWrites.add(p);
    try {
      await p;
    } finally {
      this.inflightWrites.delete(p);
    }
  }

  private async doWrite(path: string, content: string): Promise<void> {
    try {
      const abs = this.abs(path);
      await mkdir(dirname(abs), { recursive: true });
      const target = resolveWritePath(abs);
      const mode = await stat(target).then(
        (s) => s.mode,
        (err: unknown) => {
          if (isNotFound(err)) return undefined;
          throw err;
        },
      );
      replaceFileAtomically(target, content, mode);
      await this.appendVersion(path, content);
    } catch (err) {
      for (const h of this.errorHandlers) h({ error: { message: String(err), cause: err } });
    }
  }

  async flush(): Promise<void> {
    // Promise.all rejects on the first write failure; per-write errors are also
    // surfaced individually through the persist:error event channel.
    await Promise.all([...this.inflightWrites]);
  }

  async listVersions(path: string): Promise<PersistVersionEntry[]> {
    const dir = this.versionsDir(path);
    try {
      const entries = await readdir(dir);
      const sorted = entries
        .filter((f) => f.endsWith(".html"))
        .sort()
        .reverse();
      return Promise.all(
        sorted.map(async (f) => {
          const key = f.replace(/\.html$/, "");
          return {
            key,
            content: await readFile(join(dir, f), "utf8"),
            timestamp: Number(key.split("-")[0]),
          };
        }),
      );
    } catch {
      return [];
    }
  }

  async loadFrom(path: string, versionKey: string): Promise<string | undefined> {
    try {
      return await readFile(join(this.versionsDir(path), `${versionKey}.html`), "utf8");
    } catch {
      return undefined;
    }
  }

  on(event: "persist:error", handler: (e: PersistErrorEvent) => void): () => void {
    if (event !== "persist:error") return () => {};
    this.errorHandlers.push(handler);
    return () => {
      const i = this.errorHandlers.indexOf(handler);
      if (i !== -1) this.errorHandlers.splice(i, 1);
    };
  }

  private abs(path: string): string {
    return join(this.root, path);
  }

  private versionsDir(path: string): string {
    return join(this.root, ".hf-versions", path);
  }

  private async appendVersion(path: string, content: string): Promise<void> {
    const prior = this._writeLocks.get(path) ?? Promise.resolve();
    const next = prior.then(() => this._doAppendVersion(path, content));
    this._writeLocks.set(
      path,
      next.catch(() => {}),
    );
    return next;
  }

  private async _doAppendVersion(path: string, content: string): Promise<void> {
    const dir = this.versionsDir(path);
    await mkdir(dir, { recursive: true });
    const key = `${Date.now()}-${String(++_versionCounter).padStart(4, "0")}`;
    await writeFile(join(dir, `${key}.html`), content, "utf8");
    // prune oldest beyond maxVersions
    const all = (await readdir(dir)).filter((f) => f.endsWith(".html")).sort();
    const excess = all.length - this.maxVersions;
    if (excess > 0) {
      await Promise.all(all.slice(0, excess).map((f) => unlink(join(dir, f)).catch(() => {})));
    }
  }
}

function isNotFound(err: unknown): boolean {
  return (err as NodeJS.ErrnoException)?.code === "ENOENT";
}

export function createFsAdapter(opts: FsAdapterOptions): PersistAdapter {
  return new FsAdapter(opts);
}