@johnhenry/sitefile 0.0.0-stage → 0.0.1

package/lib/src/exporter.d.ts

@@ -0,0 +1,103 @@
+import type { Tree } from './tree.js';
+export interface ExportOptions {
+    /** The build context. The destination may never be, or contain, it. */
+    readonly contextDir: string;
+    /** Replace a non-empty destination outside the context. */
+    readonly force?: boolean;
+    /**
+     * TEST-ONLY. Awaited after the temp tree is fully written and immediately
+     * before the final re-validation and swap, so tests can deterministically
+     * simulate a concurrent change to the destination. Not exposed by the CLI.
+     * @internal
+     */
+    readonly beforeSwap?: () => Promise<void>;
+    /**
+     * Watch mode (directory exports only): what the previous export of this session left on
+     * disk. When the destination still holds exactly that, only the files that changed are
+     * written ({@link ExportState}); either way the export is recorded for the next one.
+     */
+    readonly incremental?: ExportState;
+    /**
+     * TEST-ONLY. Incremental export: awaited after the changed files are staged, before any
+     * of them is moved into the destination. @internal
+     */
+    readonly beforeApply?: () => Promise<void>;
+}
+export interface ExportResult {
+    /** Real absolute path the tree was written to. */
+    readonly outDir: string;
+    readonly files: number;
+    /** Set when only the changes were applied in place (incremental export). */
+    readonly incremental?: {
+        readonly written: number;
+        readonly removed: number;
+    };
+}
+/**
+ * The temp directory starts empty and the tree has no two paths equal under
+ * case folding, so EEXIST/ENOTDIR/EISDIR here means the destination file
+ * system treats two different tree paths as one name (a folding or
+ * normalization rule wider than Sitefile's). Report the artifact path, not the
+ * temp path.
+ */
+export declare function occupied(e: unknown, p: string): unknown;
+/** Matches the exporter's temporary (`tmp`) and backup (`old`) sibling names. */
+export declare const TEMP_PREFIX_PATTERN: RegExp;
+/** True if `name` is a temp/backup sibling the exporter creates for `outBasename`. */
+export declare function isExporterTempName(name: string, outBasename: string): boolean;
+/**
+ * Materialize `tree` as a directory at `outDir`. Files are written into a
+ * fresh temporary sibling, which is then swapped in; on failure the previous
+ * destination (if any) is left in place.
+ */
+export declare function exportDirectory(tree: Tree, outDir: string, options: ExportOptions): Promise<ExportResult>;
+/** What a watch session's last directory export left on disk; see {@link ExportOptions.incremental}. */
+export declare class ExportState {
+    /** @internal */
+    snapshot: Snapshot | undefined;
+    /** Forget the last export: the next one rewrites everything. */
+    clear(): void;
+}
+interface Stamp {
+    readonly dev: number;
+    readonly ino: number;
+    readonly size: number;
+    readonly mtimeMs: number;
+    readonly ctimeMs: number;
+    readonly mode: number;
+}
+interface Recorded {
+    readonly digest: string;
+    readonly mode: number;
+    readonly stamp: Stamp;
+}
+interface Snapshot {
+    readonly outReal: string;
+    readonly outId: FileId;
+    readonly parentId: FileId;
+    /** Artifact path (`/a/b.html`) → what was written there. */
+    readonly files: ReadonlyMap<string, Recorded>;
+    /** Every directory below the destination (`/a`, `/a/b`). */
+    readonly dirs: ReadonlySet<string>;
+}
+export interface ExportFileResult {
+    /** Real absolute path of the file that was written. */
+    readonly outFile: string;
+    readonly bytes: number;
+}
+/**
+ * Write `data` as a single file at `outFile` (zip, tar, tgz, wbn). Same
+ * destination rules as {@link exportDirectory}: never the filesystem root, the
+ * home directory, the build context or a parent of it; never through a symlink;
+ * a directory is refused; an existing file outside the context needs
+ * `force`. The bytes go to a temporary sibling that is renamed into place after
+ * the parent and destination are re-validated; only that exact temp file (by
+ * dev/ino) is ever deleted, and nothing already at `outFile` is removed except
+ * by the replacing rename.
+ */
+export declare function exportFile(data: Uint8Array, outFile: string, options: ExportOptions): Promise<ExportFileResult>;
+interface FileId {
+    readonly dev: number | bigint;
+    readonly ino: number | bigint;
+}
+export {};