@hologit/holo-tree 0.1.1 → 0.2.0

package/README.md

@@ -39,14 +39,26 @@ blob content crosses as `Buffer` (binary-safe).
 | `repo.createTreeFromRef(ref)` → `Tree` | `repo::create_tree_from_ref` | resolves ref→commit→tree |
 | `repo.createTree()` → `Tree` | `MutableTree::empty` | |
 | `repo.commitTree(treeHash, parents[], msg)` → hash | `repo::commit_tree` | uses git-config identity |
-| `repo.updateRef(ref, hash)` | `repo::update_ref` | |
+| `repo.updateRef(ref, hash, expectedOldHash?)` | `repo::update_ref` | compare-and-swap when `expectedOldHash` given; force otherwise |
+| `repo.resolveRef(ref)` → `hash\|null` | `repo::resolve_ref` | peels tags; `null` if unresolved |
+| `repo.writeBlob(buf)` → hash | `gix write_blob` | hash bytes into the ODB, no tree |
 | `tree.writeChild(path, text)` → hash | `MutableTree::write_child` | UTF-8 text |
 | `tree.writeChildBytes(path, buf)` → hash | `MutableTree::write_child_bytes` | binary |
 | `tree.readBlob(path)` → `Buffer\|null` | `MutableTree::read_blob` | |
+| `tree.getChild(path)` → `{type,hash,mode}\|null` | `MutableTree::get_child` | read-only; deep path |
+| `tree.getChildren(path)` → `[{name,type,hash,mode}]` | `get_subtree`+`ensure_children` | read-only; direct children |
+| `tree.getBlobMap(path?)` → `[{path,hash,mode}]` | `get_subtree`+`get_blob_map` | read-only; paths relative to subtree |
 | `tree.deleteChildDeep(path)` → bool | `MutableTree::delete_child_deep` | |
+| `tree.clearChildren(path)` | `MutableTree::clear_children` | O(1) subtree wipe |
+| `tree.merge(other, {files?, mode})` | `MutableTree::merge` | `mode`: `overlay`/`replace`/`underlay` |
 | `tree.write()` → treeHash | `MutableTree::write` | |
 | `emptyTreeHash()` → hash | `tree::empty_tree_id` | module fn |
 
+`mode` values are the git filemode as a number (e.g. `33188` = `0o100644`). Tree
+hashes reported by the read-only navigators reflect the last `write()`/load and
+are stale for a subtree mutated since — flush with `write()` for canonical
+hashes.
+
 ## Building
 
 Requires a Rust toolchain and `@napi-rs/cli` (a devDependency):
@@ -102,7 +114,7 @@ exist on npm before trusted publishing can be turned on.
    # platform packages first, then the main package:
    for d in npm/*/ ; do ( cd "$d" && npm publish --access public ); done
    npm publish --access public --ignore-scripts          # main; skip the napi
-                                                         # prepublish GH-release hook
+                                                         # prepublish hook
    ```
 
 3. **Turn on trusted publishing** on npmjs.com for **each** of the four packages
@@ -112,11 +124,14 @@ exist on npm before trusted publishing can be turned on.
 ### Releases (after bootstrap — fully automated, tokenless)
 
 ```sh
-git tag holo-tree-v0.1.0 && git push origin holo-tree-v0.1.0
+git tag holo-tree-v0.1.1 && git push origin holo-tree-v0.1.1
 ```
 
 The tag drives the published version; CI builds all three platforms, then
-publishes via OIDC (provenance + a GitHub release). No secret needed.
+publishes via OIDC (provenance). No secret needed. The `holo-tree-v*` tag is the
+release marker — napi runs with `--skip-gh-release` so it does **not** create a
+bare `v<version>` GitHub release/tag (which would collide with hologit's own
+`v*` JS-package release namespace).
 
 To add or drop a platform later, edit `napi.triples.additional` +
 `optionalDependencies` in `package.json`, run `napi create-npm-dir -t .`, add the

package/index.d.ts

@@ -17,6 +17,41 @@ export interface Signature {
   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.
  *
@@ -43,8 +78,28 @@ export declare class Repo {
    * 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. */
-  updateRef(refname: string, hash: string): void
+  /**
+   * 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. Omit it 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.
@@ -70,8 +125,37 @@ export declare class Tree {
   writeChildBytes(path: string, content: Buffer): 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
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hologit/holo-tree",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Node.js native binding for holo-tree — mutable in-memory git trees via gix",
   "main": "index.js",
   "types": "index.d.ts",
@@ -29,15 +29,15 @@
     "index.d.ts"
   ],
   "optionalDependencies": {
-    "@hologit/holo-tree-linux-x64-gnu": "0.1.1",
-    "@hologit/holo-tree-darwin-arm64": "0.1.1",
-    "@hologit/holo-tree-win32-x64-msvc": "0.1.1"
+    "@hologit/holo-tree-linux-x64-gnu": "0.2.0",
+    "@hologit/holo-tree-darwin-arm64": "0.2.0",
+    "@hologit/holo-tree-win32-x64-msvc": "0.2.0"
   },
   "scripts": {
     "artifacts": "napi artifacts",
     "build": "napi build --platform --release",
     "build:debug": "napi build --platform",
-    "prepublishOnly": "napi prepublish -t npm",
+    "prepublishOnly": "napi prepublish -t npm --skip-gh-release",
     "test": "node --test test/",
     "version": "napi version"
   },