hologit/holo-tree-napi/index.d.ts

Hologit automates the projection of layered composite file trees based on flat, declarative plans

/* tslint:disable */
/* eslint-disable */

/* auto-generated by NAPI-RS */

/** Git's well-known empty-tree hash (`4b825dc6…`). */
export declare function emptyTreeHash(): string
/**
 * The compile profile of the loaded binding: `"release"` or `"debug"`.
 *
 * The runtime guard for the release-build requirement (#464 item 4): a debug
 * build of this binding measures *slower* than the JS + `git`-subprocess path
 * it replaces (~2.4x on the reference workload), while a release build is
 * ~4–5x faster. The bundled benchmark refuses to run against a debug build;
 * consumers embedding a from-source build can use this to assert the same.
 */
export declare function buildProfile(): string
/**
 * Internal self-test hook: deliberately panics inside the binding so the
 * test suite can prove that a panic surfaces as a catchable JS error with
 * code `PANIC` rather than aborting the host process (specs/api/errors.md
 * § Panic policy). Never call this outside tests.
 */
export declare function __triggerPanicForTest(): void
/**
 * A commit identity (author or committer). `timeSeconds`/`offsetMinutes` are
 * optional; when omitted the current wall-clock time at UTC is used. Pass them
 * explicitly to reproduce a specific commit (e.g. match `git commit-tree`
 * under pinned `GIT_AUTHOR_DATE`/`GIT_COMMITTER_DATE`).
 */
export interface Signature {
  name: string
  email: string
  timeSeconds?: number
  offsetMinutes?: number
}
/**
 * A child entry returned by read-only navigation. `type` is `"tree"`,
 * `"blob"`, or `"commit"`; `mode` is the git filemode as a number
 * (e.g. `33188` = `0o100644`, `16384` = `0o040000` for a tree).
 */
export interface ChildInfo {
  type: string
  hash: string
  mode: number
}
/** A named child entry, returned by `getChildren`. */
export interface NamedChildInfo {
  name: string
  type: string
  hash: string
  mode: number
}
/**
 * A blob entry in a flattened blob map, returned by `getBlobMap`. `path` is
 * relative to the navigated subtree.
 */
export interface BlobEntry {
  path: string
  hash: string
  mode: number
}
/**
 * Options for `Tree.merge`. `mode` is `"overlay"`, `"replace"`, or
 * `"underlay"`; `files` is an optional list of glob patterns restricting which
 * paths merge (omit to merge everything).
 */
export interface MergeOpts {
  files?: Array<string>
  mode: string
}
/**
 * A handle to a git repository, backed by gix.
 *
 * Stored as a `ThreadSafeRepository` so the handle is `Send + Sync` and can be
 * cheaply cloned into each `Tree`; calls use a memoized thread-local
 * `gix::Repository` (see [`local_repo`]), re-derived only when a call lands
 * on a different thread.
 */
export declare class Repo {
  /**
   * Open a repository at `gitDir` (a `.git` directory, or any path gix can
   * discover a repo from).
   */
  static open(gitDir: string): Repo
  /**
   * Resolve a ref (branch, tag, or commit hash) to its tree and return a
   * mutable, in-memory view of it.
   */
  createTreeFromRef(gitRef: string): Tree
  /** Create a fresh empty, mutable in-memory tree rooted at this repo. */
  createTree(): Tree
  /**
   * Write a commit object pointing at `treeHash` with `parents`. `author`
   * and `committer` are optional; each falls back to the repo's configured
   * identity, then a "holo-tree" default. Returns the new commit hash.
   */
  commitTree(treeHash: string, parents: Array<string>, message: string, author?: Signature | undefined | null, committer?: Signature | undefined | null): string
  /**
   * Point a ref at an object hash.
   *
   * When `expectedOldHash` is provided this is a **compare-and-swap**: the
   * update only succeeds if the ref currently resolves to exactly that hash,
   * so a concurrent writer who moved the ref makes the swap fail rather than
   * silently clobbering their commit. A lost swap throws with code
   * `REF_CONFLICT` — the matchable optimistic-concurrency signal. Omit
   * `expectedOldHash` to force the ref (the prior unconditional behavior).
   */
  updateRef(refname: string, hash: string, expectedOldHash?: string | undefined | null): void
  /**
   * Resolve a ref / rev-spec (branch, tag, `HEAD`, hash, …) to its commit
   * hash, peeling annotated tags. Returns `null` when the ref does not
   * resolve — the natural "does this ref exist?" probe before a CAS
   * `updateRef`.
   */
  resolveRef(gitRef: string): string | null
  /**
   * Hash raw bytes as a loose blob in the ODB and return its hash, without
   * inserting it into any tree. Binary-safe.
   */
  writeBlob(content: Buffer): string
}
/**
 * A mutable, in-memory git tree.
 *
 * Holds its own clone of the repo handle so JS callers don't thread a repo
 * argument through every call.
 *
 * Owns its `TreeCache` (Phase-C finding #5): the cache travels with the
 * `Tree` object rather than living in thread-implicit state, so whichever
 * thread the JS engine dispatches a call on sees the same cache — see
 * `specs/api/errors.md` § Thread-safety expectations. Likewise owns its
 * memoized thread-local repo derivation (see [`local_repo`]).
 */
export declare class Tree {
  /**
   * Hash `content` (UTF-8 text) as a blob and insert it at `path`, creating
   * intermediate trees as needed. Returns the blob hash.
   */
  writeChild(path: string, content: string): string
  /** Hash raw bytes as a blob and insert at `path`. Binary-safe. */
  writeChildBytes(path: string, content: Buffer): string
  /**
   * Place an already-written blob at `path` by its `hash`, without reading its
   * bytes. Unlike `writeChildBytes` (which re-hashes content), this grafts a
   * blob already in the ODB — validated to exist and be a blob via a header
   * lookup, so a large attachment isn't read back and re-hashed. `mode` is the
   * git filemode: `0o100644` regular, `0o100755` executable, `0o120000`
   * symlink. Returns the placed hash.
   */
  writeChildHash(path: string, hash: string, mode: number): string
  /** Read a blob's bytes at `path`, or `null` if no blob exists there. */
  readBlob(path: string): Buffer | null
  /**
   * Read-only: look up the child at a deep `path` and report its type,
   * hash, and mode, or `null` if nothing exists there.
   */
  getChild(path: string): ChildInfo | null
  /**
   * Read-only: list the direct children of the subtree at `path` (use `"."`
   * for the root). Returns an empty array if `path` is missing or not a tree.
   */
  getChildren(path: string): Array<NamedChildInfo>
  /**
   * Read-only: recursively collect every blob under the subtree at `path`
   * (defaults to the whole tree) into a flat list. Each `path` is relative
   * to the navigated subtree. Returns an empty array if `path` is missing.
   */
  getBlobMap(path?: string | undefined | null): Array<BlobEntry>
  /** Delete a child at a deep `path`. Returns whether it existed. */
  deleteChildDeep(path: string): boolean
  /**
   * Clear all children under a deep `path` in O(1) — replace the subtree
   * there with the empty tree (and dirty its ancestors) without loading the
   * cleared subtree's contents. `path == "."` clears the whole tree. Used to
   * wipe a directory before a full rewrite.
   */
  clearChildren(path: string): void
  /**
   * Merge another tree into this one in place, per `options.mode`
   * (`overlay`/`replace`/`underlay`) and optional `options.files` globs.
   * `other` must be a *different* `Tree` instance.
   */
  merge(other: Tree, options: MergeOpts): void
  /** Flush dirty subtrees to the ODB and return the resulting tree hash. */
  write(): string
}