@relayfile/core 0.3.0 → 0.3.2

package/dist/forks.d.ts

@@ -0,0 +1,61 @@
+import type { FileSemantics } from "./storage.js";
+import type { WriteFileRequest } from "./files.js";
+export declare const DEFAULT_FORK_TTL_SECONDS: number;
+export declare const MAX_FORK_TTL_SECONDS: number;
+export interface ForkOptions {
+    workspaceId: string;
+    proposalId: string;
+    ttlSeconds?: number;
+}
+export interface ForkHandle {
+    forkId: string;
+    proposalId: string;
+    workspaceId: string;
+    expiresAt: string;
+    parentRevision: string;
+}
+export interface ForkWriteFileRequest extends Omit<WriteFileRequest, "ifMatch"> {
+    contentType?: string;
+    content: string;
+    encoding?: string;
+    semantics?: FileSemantics;
+}
+export type ForkOverlayEntry = {
+    type: "write";
+    file: ForkWriteFileRequest;
+    revision: string;
+} | {
+    type: "delete";
+    deletedAt: string;
+};
+export interface ForkState extends ForkHandle {
+    createdAt: string;
+    overlay: Record<string, ForkOverlayEntry>;
+    overlayRevisionCounter: number;
+}
+export interface CommitForkResponse {
+    revision: string;
+    writtenCount: number;
+    deletedCount: number;
+}
+export interface ParentMovedErrorPayload {
+    error: "parent_moved";
+    currentRevision: string;
+}
+export interface ForkExpiredErrorPayload {
+    error: "fork_expired";
+}
+export declare function normalizeForkTTLSeconds(ttlSeconds?: number): number;
+export declare function computeForkExpiresAt(createdAt: string | Date, ttlSeconds?: number): string;
+export declare function isForkExpired(fork: Pick<ForkState, "expiresAt">, now?: string | Date): boolean;
+export declare function nextForkOverlayRevision(forkId: string, nextCounter: number): string;
+export declare function createForkState(input: {
+    forkId: string;
+    workspaceId: string;
+    proposalId: string;
+    parentRevision: string;
+    createdAt?: string | Date;
+    ttlSeconds?: number;
+}): ForkState;
+export declare function writeForkOverlay(fork: ForkState, path: string, file: ForkWriteFileRequest): ForkOverlayEntry;
+export declare function deleteForkOverlay(fork: ForkState, path: string, deletedAt?: string | Date): ForkOverlayEntry;

package/dist/forks.js

@@ -0,0 +1,62 @@
+import { normalizePath } from "./files.js";
+export const DEFAULT_FORK_TTL_SECONDS = 7 * 24 * 60 * 60;
+export const MAX_FORK_TTL_SECONDS = 30 * 24 * 60 * 60;
+export function normalizeForkTTLSeconds(ttlSeconds) {
+    if (ttlSeconds === undefined) {
+        return DEFAULT_FORK_TTL_SECONDS;
+    }
+    if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0) {
+        return DEFAULT_FORK_TTL_SECONDS;
+    }
+    return Math.min(Math.floor(ttlSeconds), MAX_FORK_TTL_SECONDS);
+}
+export function computeForkExpiresAt(createdAt, ttlSeconds) {
+    const created = typeof createdAt === "string" ? new Date(createdAt) : createdAt;
+    const ttlMs = normalizeForkTTLSeconds(ttlSeconds) * 1000;
+    return new Date(created.getTime() + ttlMs).toISOString();
+}
+export function isForkExpired(fork, now = new Date()) {
+    const nowMs = typeof now === "string" ? Date.parse(now) : now.getTime();
+    return Number.isFinite(nowMs) && nowMs >= Date.parse(fork.expiresAt);
+}
+export function nextForkOverlayRevision(forkId, nextCounter) {
+    return `fork:${forkId}:${nextCounter}`;
+}
+export function createForkState(input) {
+    const createdAt = input.createdAt instanceof Date
+        ? input.createdAt.toISOString()
+        : input.createdAt ?? new Date().toISOString();
+    return {
+        forkId: input.forkId,
+        workspaceId: input.workspaceId,
+        proposalId: input.proposalId,
+        parentRevision: input.parentRevision,
+        createdAt,
+        expiresAt: computeForkExpiresAt(createdAt, input.ttlSeconds),
+        overlay: {},
+        overlayRevisionCounter: 0,
+    };
+}
+export function writeForkOverlay(fork, path, file) {
+    const nextCounter = fork.overlayRevisionCounter + 1;
+    const revision = nextForkOverlayRevision(fork.forkId, nextCounter);
+    const entry = {
+        type: "write",
+        file: {
+            ...file,
+            path: normalizePath(path),
+        },
+        revision,
+    };
+    fork.overlayRevisionCounter = nextCounter;
+    fork.overlay[normalizePath(path)] = entry;
+    return entry;
+}
+export function deleteForkOverlay(fork, path, deletedAt = new Date()) {
+    const entry = {
+        type: "delete",
+        deletedAt: deletedAt instanceof Date ? deletedAt.toISOString() : deletedAt,
+    };
+    fork.overlay[normalizePath(path)] = entry;
+    return entry;
+}

package/dist/forks.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/forks.test.js

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import { DEFAULT_FORK_TTL_SECONDS, MAX_FORK_TTL_SECONDS, computeForkExpiresAt, createForkState, deleteForkOverlay, isForkExpired, nextForkOverlayRevision, normalizeForkTTLSeconds, writeForkOverlay, } from "./forks.js";
+describe("fork helpers", () => {
+    it("normalizes ttl seconds with the documented default and max", () => {
+        expect(normalizeForkTTLSeconds()).toBe(DEFAULT_FORK_TTL_SECONDS);
+        expect(normalizeForkTTLSeconds(0)).toBe(DEFAULT_FORK_TTL_SECONDS);
+        expect(normalizeForkTTLSeconds(MAX_FORK_TTL_SECONDS + 1)).toBe(MAX_FORK_TTL_SECONDS);
+    });
+    it("computes expiresAt from creation time", () => {
+        expect(computeForkExpiresAt("2026-04-21T00:00:00.000Z", 60)).toBe("2026-04-21T00:01:00.000Z");
+    });
+    it("tracks overlay revisions without colliding with parent revisions", () => {
+        const fork = createForkState({
+            forkId: "fork_123",
+            workspaceId: "ws_1",
+            proposalId: "prop_1",
+            parentRevision: "rev_1",
+            createdAt: "2026-04-21T00:00:00.000Z",
+        });
+        const first = writeForkOverlay(fork, "docs/a.md", {
+            path: "docs/a.md",
+            content: "# a",
+        });
+        const second = writeForkOverlay(fork, "/docs/b.md", {
+            path: "/docs/b.md",
+            content: "# b",
+        });
+        expect(first).toMatchObject({ type: "write", revision: "fork:fork_123:1" });
+        expect(second).toMatchObject({ type: "write", revision: "fork:fork_123:2" });
+        expect(nextForkOverlayRevision("fork_123", 3)).toBe("fork:fork_123:3");
+        expect(Object.keys(fork.overlay)).toEqual(["/docs/a.md", "/docs/b.md"]);
+    });
+    it("stores delete tombstones by normalized path", () => {
+        const fork = createForkState({
+            forkId: "fork_123",
+            workspaceId: "ws_1",
+            proposalId: "prop_1",
+            parentRevision: "rev_1",
+        });
+        deleteForkOverlay(fork, "docs/a.md", "2026-04-21T00:00:00.000Z");
+        expect(fork.overlay["/docs/a.md"]).toEqual({
+            type: "delete",
+            deletedAt: "2026-04-21T00:00:00.000Z",
+        });
+    });
+    it("detects expired forks", () => {
+        const fork = createForkState({
+            forkId: "fork_123",
+            workspaceId: "ws_1",
+            proposalId: "prop_1",
+            parentRevision: "rev_1",
+            createdAt: "2026-04-21T00:00:00.000Z",
+            ttlSeconds: 60,
+        });
+        expect(isForkExpired(fork, "2026-04-21T00:00:59.000Z")).toBe(false);
+        expect(isForkExpired(fork, "2026-04-21T00:01:00.000Z")).toBe(true);
+    });
+});

package/dist/index.d.ts

@@ -16,3 +16,4 @@ export * from "./writeback.js";
 export * from "./webhooks.js";
 export * from "./export.js";
 export * from "./dedup.js";
+export * from "./forks.js";

package/dist/index.js

@@ -16,3 +16,4 @@ export * from "./writeback.js";
 export * from "./webhooks.js";
 export * from "./export.js";
 export * from "./dedup.js";
+export * from "./forks.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/core",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Shared business logic for relayfile — file operations, ACL, queries, events, and writeback lifecycle",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,6 +14,7 @@
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
+    "@types/node": "^22.0.0",
     "typescript": "^5.7.3",
     "vitest": "^3.0.0"
   },