@gitsheets/core-napi 0.8.0 → 0.9.0

package/binding.cjs

@@ -79,6 +79,16 @@ class ContractError extends GitsheetsError {
   }
 }
 
+class AggregationError extends GitsheetsError {
+  constructor(message, opts = {}) {
+    super(message, opts);
+    this.name = 'AggregationError';
+    if (opts.sheet !== undefined) this.sheet = opts.sheet;
+    if (opts.aggregate !== undefined) this.aggregate = opts.aggregate;
+    if (opts.partition !== undefined) this.partition = opts.partition;
+  }
+}
+
 const CLASS_BY_NAME = {
   ConfigError,
   ValidationError,
@@ -88,6 +98,7 @@ const CLASS_BY_NAME = {
   PathTemplateError,
   NotFoundError,
   ContractError,
+  AggregationError,
 };
 
 // Map a structured error raised by the addon onto its typed class. The mapping
@@ -98,6 +109,9 @@ function mapCoreError(raw) {
   if (raw.issues !== undefined) opts.issues = raw.issues;
   if (raw.conflictingPaths !== undefined) opts.conflictingPaths = raw.conflictingPaths;
   if (raw.contract !== undefined) opts.contract = raw.contract;
+  if (raw.sheet !== undefined) opts.sheet = raw.sheet;
+  if (raw.aggregate !== undefined) opts.aggregate = raw.aggregate;
+  if (raw.partition !== undefined) opts.partition = raw.partition;
   return new Cls(raw.message, opts);
 }
 
@@ -149,6 +163,15 @@ module.exports = {
   // the filter (equality / nested / `$pred` engine snippets) runs in the core.
   recordQuery: wrap(addon.recordQuery),
   recordQueryCandidates: wrap(addon.recordQueryCandidates),
+  // Ad-hoc aggregation (behaviors/aggregation.md): a malformed spec throws a
+  // plain TypeError; a data-dependent failure an AggregationError.
+  recordAggregate: wrap(addon.recordAggregate),
+  // Rollup sheets (behaviors/rollups.md): the stamped read-through and the
+  // non-fresh survey, opening the rollup sheet from the tree each call.
+  rollupQuery: wrap(addon.rollupQuery),
+  rollupGet: wrap(addon.rollupGet),
+  rollupStatus: wrap(addon.rollupStatus),
+  rollupAggregate: wrap(addon.rollupAggregate),
   treeReadBlob: wrap(addon.treeReadBlob),
   treeEntryHash: wrap(addon.treeEntryHash),
   blobRead: wrap(addon.blobRead),
@@ -207,4 +230,5 @@ module.exports = {
   PathTemplateError,
   NotFoundError,
   ContractError,
+  AggregationError,
 };

package/index.d.ts

@@ -248,6 +248,19 @@ export declare function substrateReset(): void
  * bytes itself (spec: `rust-core.md` "Query traversal + filtering").
  */
 export declare function recordQuery(gitDir: string, treeRef: string, base: string, template: string, filter: object, extension?: string | undefined | null, bodyField?: string | undefined | null, titleField?: string | undefined | null, withBody?: boolean | undefined | null): Array<JsRecordEntry>
+/**
+ * Ad-hoc aggregation over the sheet under `base` in `treeRef`: the records
+ * matching `filter` (pruned by `template`, read body-less, the filter
+ * applied in the core — the same forms `recordQuery` takes) folded in
+ * canonical path order by the `aggregates` table (count / sum / avg / min /
+ * max / distinct / reduce, each with optional `where` / `groupBy`). Returns
+ * one value per aggregate name. `paths`, when given, restricts the
+ * contributing set to those record paths (the binding admits records with
+ * host-side predicates first). A malformed spec throws `TypeError`; a
+ * data-dependent failure throws `AggregationError` (`aggregation_failed`)
+ * carrying `sheet` and `aggregate`. Batch-first: one FFI crossing.
+ */
+export declare function recordAggregate(gitDir: string, treeRef: string, sheet: string, base: string, template: string, filter: object, aggregates: unknown, extension?: string | undefined | null, bodyField?: string | undefined | null, titleField?: string | undefined | null, paths?: Array<string> | undefined | null): JsValue
 /**
  * A blob read by `treeRef:path` — the bytes plus the blob's object id, or
  * `null` when nothing (or a subtree) lives at `path`. Backs sheet-config
@@ -414,6 +427,45 @@ export interface JsAttachmentEntry {
   name: string
   hash: string
 }
+/** `materialize()`'s result: the rollup record paths written and deleted. */
+export interface JsMaterializeOutcome {
+  recomputed: Array<string>
+  deleted: Array<string>
+}
+/**
+ * One non-fresh rollup partition: its rollup record path and status
+ * (`stale` / `missing` / `orphaned`).
+ */
+export interface JsRollupEntry {
+  path: string
+  status: string
+}
+/**
+ * Read a rollup sheet through its source (spec: `behaviors/rollups.md`
+ * "Reads"): partitions pruned by `filter` (the `recordQuery` forms), each
+ * served from its stored record when its `sourceTree` stamp matches and
+ * recomputed transiently otherwise; orphans are not yielded. `stale:
+ * 'serve'` returns the stored records as committed. Sorted by path.
+ */
+export declare function rollupQuery(gitDir: string, treeRef: string, name: string, configPath: string, openRoot: string, prefix: string, filter: object, stale?: string | undefined | null): Array<JsRecordEntry>
+/**
+ * One rollup record by path, read through its source (`stale` as on
+ * `rollupQuery`). `null` when no partition is there.
+ */
+export declare function rollupGet(gitDir: string, treeRef: string, name: string, configPath: string, openRoot: string, prefix: string, path: string, stale?: string | undefined | null): JsValue | null
+/**
+ * Ad-hoc aggregation over a rollup sheet's **read-through** records (spec:
+ * `behaviors/rollups.md` "Reads"): the rows `rollupQuery` would yield for
+ * `filter`, folded by `aggregates` like `recordAggregate` (same forms,
+ * `paths`, and errors). A rollup sheet's stored bytes may be stale, so the
+ * stateless `recordAggregate` over its root is not used.
+ */
+export declare function rollupAggregate(gitDir: string, treeRef: string, name: string, configPath: string, openRoot: string, prefix: string, filter: object, aggregates: unknown, paths?: Array<string> | undefined | null): JsValue
+/**
+ * The non-fresh partitions of a rollup sheet at `treeRef` — `git sheet
+ * rollup --check`. Writes nothing.
+ */
+export declare function rollupStatus(gitDir: string, treeRef: string, name: string, configPath: string, openRoot: string, prefix: string): Array<JsRollupEntry>
 /** Options for [`sync_branch`]. */
 export interface JsSyncOptions {
   /** Local branch (bare name or qualified ref). */
@@ -678,14 +730,21 @@ export declare class CoreTransaction {
    * as `recordQuery` (equality / nested / `$pred` / ranges). Read-only —
    * does not mark the transaction mutated.
    */
-  query(name: string, filter: object, withBody: boolean): Array<JsRecordEntry>
+  query(name: string, filter: object, withBody: boolean, stale?: string | undefined | null): Array<JsRecordEntry>
+  /**
+   * Ad-hoc aggregation over the sheet's records in the transaction's
+   * private tree — the tx-bound `Sheet.aggregate` (spec:
+   * `behaviors/aggregation.md`). Same filter / aggregates / `paths` forms
+   * and errors as `recordAggregate`; reads body-less. Read-only.
+   */
+  aggregate(name: string, filter: object, aggregates: unknown, paths?: Array<string> | undefined | null): JsValue
   /**
    * Read the one record at `recordPath` (relative to the sheet's base, no
    * extension) in the transaction's private tree, decoded through the format
    * codec — the tx-bound `Sheet.get`. `null` when absent; `withBody` is the
    * lazy-body switch. Read-only.
    */
-  readRecord(name: string, recordPath: string, withBody: boolean): JsValue | null
+  readRecord(name: string, recordPath: string, withBody: boolean, stale?: string | undefined | null): JsValue | null
   /**
    * A raw file at `path` (repo-root-relative) in this transaction's
    * private tree — staged writes included — as `{ hash, content }`, or
@@ -693,8 +752,27 @@ export declare class CoreTransaction {
    * loading (specs/api/transaction.md "Read isolation").
    */
   readFile(path: string): JsBlobEntry | null
+  /**
+   * `rollupSheet.materialize()` into this transaction's private tree
+   * (spec: `behaviors/rollups.md` "Materializing explicitly"): recompute
+   * every stale or missing rollup record and delete orphaned ones. Marks
+   * the transaction mutated only when something changed. `TypeError` on a
+   * non-rollup sheet.
+   */
+  materialize(name: string): JsMaterializeOutcome
+  /**
+   * The non-fresh partitions of a rollup sheet in this transaction's tree
+   * (`stale` / `missing` / `orphaned`), writing nothing. `TypeError` on a
+   * non-rollup sheet.
+   */
+  rollupStatus(name: string): Array<JsRollupEntry>
   /** The parent commit hash captured at open (null on a fresh repo). */
   parentCommitHash(): string | null
+  /**
+   * Whether a mutating method has run in this transaction — the flag the
+   * core's no-op short-circuit at finalize reads. False once finalized.
+   */
+  isMutated(): boolean
   /**
    * Finalize: commit-on-success-only with no-op detection + `parent_moved`
    * re-check + CAS ref movement. Consumes the transaction.

package/index.js

@@ -310,7 +310,7 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { roundtrip, parseRecords, serializeRecords, renderPathsBatch, validateBatch, canonicalContractHash, validateContractName, contractPath, checkContractDocument, contractLoad, verifySheetContract, runComparator, collatorSort, CompiledDefinition, recordRead, recordWrite, recordDelete, recordList, writeBlob, substrateStats, substrateReset, recordQuery, treeReadBlob, treeEntryHash, blobRead, blobHeader, treeList, tagSet, recordQueryCandidates, templateFieldNames, recordIndexUnique, recordIndexMulti, createPatch, applyMergePatch, diffRecords, simulateCoreError, CoreTransaction, syncBranch, isAncestor, mergeSheets, mergeRecordTexts, coreDiscoverSheets, sheetConfigCheck, coreCheckValidators, markdownSerialize, markdownNormalizeBody, markdownParse, markdownParseHeaderOnly, markdownExtractH1, markdownRewriteH1 } = nativeBinding
+const { roundtrip, parseRecords, serializeRecords, renderPathsBatch, validateBatch, canonicalContractHash, validateContractName, contractPath, checkContractDocument, contractLoad, verifySheetContract, runComparator, collatorSort, CompiledDefinition, recordRead, recordWrite, recordDelete, recordList, writeBlob, substrateStats, substrateReset, recordQuery, recordAggregate, treeReadBlob, treeEntryHash, blobRead, blobHeader, treeList, tagSet, recordQueryCandidates, templateFieldNames, recordIndexUnique, recordIndexMulti, createPatch, applyMergePatch, diffRecords, simulateCoreError, CoreTransaction, rollupQuery, rollupGet, rollupAggregate, rollupStatus, syncBranch, isAncestor, mergeSheets, mergeRecordTexts, coreDiscoverSheets, sheetConfigCheck, coreCheckValidators, markdownSerialize, markdownNormalizeBody, markdownParse, markdownParseHeaderOnly, markdownExtractH1, markdownRewriteH1 } = nativeBinding
 
 module.exports.roundtrip = roundtrip
 module.exports.parseRecords = parseRecords
@@ -334,6 +334,7 @@ module.exports.writeBlob = writeBlob
 module.exports.substrateStats = substrateStats
 module.exports.substrateReset = substrateReset
 module.exports.recordQuery = recordQuery
+module.exports.recordAggregate = recordAggregate
 module.exports.treeReadBlob = treeReadBlob
 module.exports.treeEntryHash = treeEntryHash
 module.exports.blobRead = blobRead
@@ -349,6 +350,10 @@ module.exports.applyMergePatch = applyMergePatch
 module.exports.diffRecords = diffRecords
 module.exports.simulateCoreError = simulateCoreError
 module.exports.CoreTransaction = CoreTransaction
+module.exports.rollupQuery = rollupQuery
+module.exports.rollupGet = rollupGet
+module.exports.rollupAggregate = rollupAggregate
+module.exports.rollupStatus = rollupStatus
 module.exports.syncBranch = syncBranch
 module.exports.isAncestor = isAncestor
 module.exports.mergeSheets = mergeSheets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitsheets/core-napi",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Node.js native binding for gitsheets-core — the FFI marshalling boundary.",
   "main": "binding.cjs",
   "types": "index.d.ts",
@@ -33,19 +33,19 @@
     "index.d.ts"
   ],
   "optionalDependencies": {
-    "@gitsheets/core-napi-linux-x64-gnu": "0.8.0",
-    "@gitsheets/core-napi-linux-arm64-gnu": "0.8.0",
-    "@gitsheets/core-napi-linux-x64-musl": "0.8.0",
-    "@gitsheets/core-napi-darwin-arm64": "0.8.0",
-    "@gitsheets/core-napi-darwin-x64": "0.8.0",
-    "@gitsheets/core-napi-win32-x64-msvc": "0.8.0"
+    "@gitsheets/core-napi-linux-x64-gnu": "0.9.0",
+    "@gitsheets/core-napi-linux-arm64-gnu": "0.9.0",
+    "@gitsheets/core-napi-linux-x64-musl": "0.9.0",
+    "@gitsheets/core-napi-darwin-arm64": "0.9.0",
+    "@gitsheets/core-napi-darwin-x64": "0.9.0",
+    "@gitsheets/core-napi-win32-x64-msvc": "0.9.0"
   },
   "scripts": {
     "artifacts": "napi artifacts",
     "build": "napi build --platform --release",
     "build:debug": "napi build --platform",
     "prepublishOnly": "napi prepublish -t npm --skip-gh-release",
-    "test": "node --test test/roundtrip.mjs test/errors.mjs test/canonical.mjs test/path-template.mjs test/validation-parity.mjs test/engine-parity.mjs test/collator-parity.mjs test/record-crud.mjs test/record-query.mjs test/record-index.mjs test/sheet-store.mjs test/sheet-markdown.mjs test/sheet-attachments.mjs test/contracts.mjs test/sheet-config-check.mjs test/orphan-and-files.mjs",
+    "test": "node --test test/roundtrip.mjs test/errors.mjs test/canonical.mjs test/path-template.mjs test/validation-parity.mjs test/engine-parity.mjs test/collator-parity.mjs test/record-crud.mjs test/record-query.mjs test/record-aggregate.mjs test/record-index.mjs test/sheet-store.mjs test/sheet-markdown.mjs test/sheet-attachments.mjs test/contracts.mjs test/sheet-config-check.mjs test/orphan-and-files.mjs test/rollups.mjs",
     "bench": "node bench/query-bench.mjs",
     "version": "napi version"
   },