@cloudbitmaps/core 0.21.0 → 0.22.0

package/README.md

@@ -7,9 +7,18 @@ when you install the two packages you want. Install those instead:
 pnpm add @cloudbitmaps/roaring @cloudbitmaps/s3   # the store, and the storage you have (or /gcs, or /azure-blob)
 ```
 
-On npm 12 and pnpm 10 and later, allow `roaring`'s one install script first, or the install exits 0 and the package throws at `import`. Put this in your `package.json`: `{ "allowScripts": { "roaring": true }, "pnpm": { "onlyBuiltDependencies": ["roaring"] } }`. npm 11 runs the script but warns until you allow it the same way; pnpm 9 needs nothing extra. [Details](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/getting-started.md#cannot-find-module-buildreleaseroaringnode-after-a-successful-install).
+`roaring` needs its one install script to fetch its native binary, and newer clients run a dependency's script only if you allow it. Allow it before you install:
 
-Depend on `@cloudbitmaps/core` directly only to write a flavor or a driver.
+- **npm 12:** add `{ "allowScripts": { "roaring": true } }` to your `package.json`. Without it the install exits 0 and the package throws at `import`. npm 11 runs the script but warns until you allow it the same way.
+- **pnpm 11 and later:** put `allowBuilds: { roaring: true }` in a `pnpm-workspace.yaml` beside your `package.json`. Those versions no longer read the `package.json` `pnpm` key. Without it the install exits 1 with `ERR_PNPM_IGNORED_BUILDS`.
+- **pnpm 10:** add `{ "pnpm": { "onlyBuiltDependencies": ["roaring"] } }` to your `package.json`. Without it the install exits 0 and the package throws at `import`.
+- **pnpm 9:** nothing extra.
+
+[Details](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/getting-started.md#cannot-find-module-buildreleaseroaringnode-after-a-successful-install).
+
+Depend on `@cloudbitmaps/core` directly only to write a driver, through `@cloudbitmaps/core/driver-kit`.
+
+> **The main entry of this package is internal.** It is the engine `@cloudbitmaps/roaring` and the driver packages are built on, and it is outside the stability promise: it can change in any minor release, and a change to it gets no CHANGELOG Breaking entry. Install `@cloudbitmaps/roaring` and a driver. The public entry here is `@cloudbitmaps/core/driver-kit`, the contract for writing a driver.
 
 > **ESM-only, Node ≥ 22.12.** Use `import`; for `require()`, Jest and TypeScript, see
 > [CommonJS, Jest and TypeScript](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/getting-started.md#commonjs-jest-and-typescript).
@@ -24,9 +33,11 @@ and crypto-shred, erasure by rewrite, retention, and the in-memory and local-fil
 dependencies and no cloud SDK**. The cloud backends are their own packages, built against
 `@cloudbitmaps/core/driver-kit`, the declared contract a driver depends on. A third-party driver can use it too.
 
-Its main entry is the flavor-author kit: the read engine, the standalone forms of the store's methods (`loadSegment`,
-`dropSegment`, `retireExpired` and the rest), and the retry and budget internals. `@cloudbitmaps/roaring` re-exports,
-by name, what an application uses.
+Its main entry is the internal engine (the read engine, the standalone forms of the store's methods, and the retry and
+budget internals) that `@cloudbitmaps/roaring` and the driver packages import; it is not a public API. What an
+application uses is re-exported, by name, from `@cloudbitmaps/roaring`. The driver contracts (the storage and registry
+ports, the registry's record types, the read-source and keystore ports) are exported by `@cloudbitmaps/core/driver-kit`
+alone, which is complete: every type its signatures name is exported there too.
 
 ## How the storage path is laid out
 

package/dist/{chunk-IGLIZBR7.js → chunk-OSU7W2Y3.js}

@@ -3,7 +3,7 @@ var ERROR_BRAND = /* @__PURE__ */ Symbol.for("cloudbitmaps.error");
 var TRANSIENT_BRAND = /* @__PURE__ */ Symbol.for("cloudbitmaps.error.transient");
 var NAMES = /* @__PURE__ */ new WeakMap();
 var CloudRoaringError = class extends Error {
-  /** Cross-bundle brand — see the predicates ({@link isCloudRoaringError}, …). Non-enumerable-ish (symbol key ⇒ not in JSON). */
+  /** Cross-bundle brand — see {@link errorKind}. Non-enumerable-ish (symbol key ⇒ not in JSON). */
   [ERROR_BRAND] = true;
   constructor(message) {
     super(message);
@@ -12,6 +12,7 @@ var CloudRoaringError = class extends Error {
 };
 var ValidationError = class extends CloudRoaringError {
 };
+var CONTENTION_NEXT_STEP = "; another writer changed the segment's row while this call ran. Re-run the call: it reads the row afresh";
 var WriteConflictError = class extends CloudRoaringError {
 };
 var IntegrityError = class extends CloudRoaringError {
@@ -48,6 +49,21 @@ var UnsupportedError = class extends CloudRoaringError {
 var CapabilityError = class extends CloudRoaringError {
 };
 var BudgetExceededError = class extends CloudRoaringError {
+  /** The option to raise to let the call through. */
+  option;
+  /** The bound in force: requests, bytes or rows, by `option`. */
+  limit;
+  /**
+   * What the call had reached when refused. By `option`: the requests the call needs (`'budget.maxRequests'`), a
+   * lower bound on the resident bytes it needs (`'maxBufferedBytes'`), or `limit + 1` (`'maxScanSegments'`).
+   */
+  spent;
+  constructor(message, details) {
+    super(message);
+    this.option = details.option;
+    this.limit = details.limit;
+    this.spent = details.spent;
+  }
 };
 var KeyUnavailableError = class extends CloudRoaringError {
 };
@@ -84,15 +100,6 @@ function isWriteConflictError(err) {
 function isTransientError(err) {
   return hasBrand(err, TRANSIENT_BRAND);
 }
-function isLeaseExpiredError(err) {
-  return isCloudRoaringError(err) && err.name === "LeaseExpiredError";
-}
-function isStaleOperandError(err) {
-  return isCloudRoaringError(err) && err.name === "StaleOperandError";
-}
-function isLeaseLimitError(err) {
-  return isCloudRoaringError(err) && err.name === "LeaseLimitError";
-}
 function isNotFoundError(err) {
   return isCloudRoaringError(err) && err.name === "NotFoundError";
 }
@@ -102,26 +109,56 @@ function isIntegrityError(err) {
 function isValidationError(err) {
   return isCloudRoaringError(err) && err.name === "ValidationError";
 }
-function isUnsupportedError(err) {
-  return isCloudRoaringError(err) && err.name === "UnsupportedError";
-}
-function isCapabilityError(err) {
-  return isCloudRoaringError(err) && err.name === "CapabilityError";
-}
-function isBudgetExceededError(err) {
-  return isCloudRoaringError(err) && err.name === "BudgetExceededError";
-}
 function isKeyUnavailableError(err) {
   return isCloudRoaringError(err) && err.name === "KeyUnavailableError";
 }
+var KIND_NAMES = {
+  CloudRoaringError: true,
+  ValidationError: true,
+  WriteConflictError: true,
+  IntegrityError: true,
+  NotFoundError: true,
+  UnsupportedError: true,
+  CapabilityError: true,
+  TransientError: true,
+  KeyUnavailableError: true,
+  BudgetExceededError: true,
+  LeaseExpiredError: true,
+  LeaseLimitError: true,
+  StaleOperandError: true
+};
+function errorKind(err) {
+  if (hasBrand(err, TRANSIENT_BRAND)) return "TransientError";
+  if (!hasBrand(err, ERROR_BRAND)) return void 0;
+  const name = err.name;
+  return typeof name === "string" && Object.hasOwn(KIND_NAMES, name) ? name : "CloudRoaringError";
+}
 
 // src/core/bit-route.ts
 var U32_MAX = 4294967295;
 var CHUNK_COUNT = 65536;
 var LOW_16 = 65535;
+var idErrors = /* @__PURE__ */ new WeakSet();
+function isBadIdError(err) {
+  return err instanceof ValidationError && idErrors.has(err);
+}
+function badId(id) {
+  let got;
+  if (id === null) got = "null";
+  else if (id === void 0) got = "undefined";
+  else if (typeof id === "object") got = "an object";
+  else if (typeof id !== "number") got = `${/^[aeiou]/.test(typeof id) ? "an" : "a"} ${typeof id}`;
+  else if (!Number.isFinite(id)) got = "NaN or an infinity";
+  else if (id < 0) got = "a negative number";
+  else if (!Number.isInteger(id)) got = "a number with a fraction";
+  else got = `a number above ${U32_MAX} (ids are 32-bit)`;
+  const err = new ValidationError(`an id must be an integer from 0 to ${U32_MAX}; got ${got}`);
+  idErrors.add(err);
+  return err;
+}
 function splitId(id) {
   if (!Number.isInteger(id) || id < 0 || id > U32_MAX) {
-    throw new ValidationError(`an id must be an integer from 0 to ${U32_MAX}`);
+    throw badId(id);
   }
   return { chunkKey: id >>> 16, remainder: id & LOW_16 };
 }
@@ -322,7 +359,13 @@ function validatePart(value, field) {
     );
   }
 }
+function requireRefObject(ref, hint = "") {
+  if (typeof ref !== "object" || ref === null) {
+    throw new ValidationError(`a segment ref is an object such as { segment: 'name' }${hint}`);
+  }
+}
 function validateSegmentRef(ref) {
+  requireRefObject(ref);
   validatePart(ref.segment, "segment");
   if (ref.namespace !== void 0) validatePart(ref.namespace, "namespace");
 }
@@ -339,6 +382,7 @@ function validateUserNamespace(namespace) {
   }
 }
 function validateUserRef(ref) {
+  requireRefObject(ref, "; store.segment() takes the bare name");
   validatePart(ref.segment, "segment");
   if (ref.namespace !== void 0) validateUserNamespace(ref.namespace);
 }
@@ -657,7 +701,9 @@ async function takeLease(ref, deps, take) {
     }
   }
   if (unanswered !== void 0) throw unanswered;
-  throw new WriteConflictError(`lease: contention taking a lease on segment "${ref.segment}"`);
+  throw new WriteConflictError(
+    `lease: contention taking a lease on segment "${ref.segment}"${CONTENTION_NEXT_STEP}`
+  );
 }
 async function releaseLease(ref, deps, holder) {
   let resends = 0;
@@ -691,7 +737,9 @@ async function releaseLease(ref, deps, holder) {
     }
   }
   if (unanswered !== void 0) throw unanswered;
-  throw new WriteConflictError(`lease: contention releasing a lease on segment "${ref.segment}"`);
+  throw new WriteConflictError(
+    `lease: contention releasing a lease on segment "${ref.segment}"${CONTENTION_NEXT_STEP}`
+  );
 }
 
 // src/drivers/_shared/keys.ts
@@ -1752,6 +1800,7 @@ function entropyIsAvailable(entropy) {
 export {
   CloudRoaringError,
   ValidationError,
+  CONTENTION_NEXT_STEP,
   WriteConflictError,
   IntegrityError,
   NotFoundError,
@@ -1763,24 +1812,19 @@ export {
   BudgetExceededError,
   KeyUnavailableError,
   TransientError,
-  isCloudRoaringError,
   isWriteConflictError,
   isTransientError,
-  isLeaseExpiredError,
-  isStaleOperandError,
-  isLeaseLimitError,
   isNotFoundError,
   isIntegrityError,
   isValidationError,
-  isUnsupportedError,
-  isCapabilityError,
-  isBudgetExceededError,
   isKeyUnavailableError,
+  errorKind,
   requireInteger,
   requirePositiveInteger,
   requireFiniteNumber,
   U32_MAX,
   CHUNK_COUNT,
+  isBadIdError,
   splitId,
   MAX_REMAINDER,
   joinId,
@@ -1879,4 +1923,4 @@ export {
   requirePositiveInt,
   requireBool
 };
-//# sourceMappingURL=chunk-IGLIZBR7.js.map
+//# sourceMappingURL=chunk-OSU7W2Y3.js.map