@peerbit/blocks-interface 2.1.7 → 2.1.8

package/dist/src/index.d.ts

@@ -17,7 +17,47 @@ export type CrashSafeBlockDurability = {
     readonly crashSafe: true;
     barrier(): MaybePromise<void>;
 };
+/**
+ * Scope across which local references to a content-addressed block may alias.
+ *
+ * `block-service` is the scope of Peerbit's built-in stores: the backing
+ * namespace belongs to one blocks service, but every program using that
+ * service shares it. `caller-exclusive` is an explicit assertion that the
+ * declaring caller controls the entire physical namespace and every reference
+ * in it. `shared` means references may exist outside this block service;
+ * `unknown` makes no reliable scope assertion. Neither persistence nor a
+ * backend class implies any scope.
+ */
+export type BlockStoreReferenceDomain = "block-service" | "caller-exclusive" | "shared" | "unknown";
+/**
+ * Immutable facts needed before a caller considers physical block deletion.
+ *
+ * `enforcedReclamation: "none"` means the store exposes no reference-safe
+ * lease, fencing, atomic delete-if-unreferenced, or isolated-namespace
+ * primitive. A raw `rm` is therefore safe only for an authority that controls
+ * the complete reference domain. This field is deliberately separate from
+ * `persisted()`.
+ */
+export type BlockStoreSafety = Readonly<{
+    referenceDomain: BlockStoreReferenceDomain;
+    enforcedReclamation: "none";
+}>;
+export declare const UNKNOWN_BLOCK_STORE_SAFETY: BlockStoreSafety;
+export declare const BLOCK_SERVICE_BLOCK_STORE_SAFETY: BlockStoreSafety;
+/**
+ * Validate, defensively copy, and freeze block-store safety metadata.
+ *
+ * The input is intentionally `unknown`: declarations can cross JavaScript and
+ * configuration boundaries where TypeScript's static shape is unavailable.
+ */
+export declare const normalizeBlockStoreSafety: (value: unknown) => BlockStoreSafety;
 export interface Blocks extends WaitForPeer {
+    /**
+     * Safety metadata for this service's local physical block namespace.
+     * Absence is equivalent to {@link UNKNOWN_BLOCK_STORE_SAFETY} so older and
+     * custom implementations fail closed.
+     */
+    readonly localStoreSafety?: BlockStoreSafety;
     put(data: Uint8Array | {
         block: Block<any, any, any, any>;
         cid: string;

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/src/index.js

@@ -1,4 +1,39 @@
 import {} from "@peerbit/stream-interface";
 import {} from "multiformats/block";
+export const UNKNOWN_BLOCK_STORE_SAFETY = Object.freeze({
+    referenceDomain: "unknown",
+    enforcedReclamation: "none",
+});
+export const BLOCK_SERVICE_BLOCK_STORE_SAFETY = Object.freeze({
+    referenceDomain: "block-service",
+    enforcedReclamation: "none",
+});
+/**
+ * Validate, defensively copy, and freeze block-store safety metadata.
+ *
+ * The input is intentionally `unknown`: declarations can cross JavaScript and
+ * configuration boundaries where TypeScript's static shape is unavailable.
+ */
+export const normalizeBlockStoreSafety = (value) => {
+    if (value === undefined)
+        return UNKNOWN_BLOCK_STORE_SAFETY;
+    if (value === null || typeof value !== "object") {
+        throw new TypeError("Invalid block-store safety metadata");
+    }
+    const referenceDomain = value
+        .referenceDomain;
+    const enforcedReclamation = value
+        .enforcedReclamation;
+    if (referenceDomain !== "block-service" &&
+        referenceDomain !== "caller-exclusive" &&
+        referenceDomain !== "shared" &&
+        referenceDomain !== "unknown") {
+        throw new TypeError("Invalid block-store reference domain");
+    }
+    if (enforcedReclamation !== "none") {
+        throw new TypeError("Unsupported block-store reclamation capability");
+    }
+    return Object.freeze({ referenceDomain, enforcedReclamation });
+};
 export { cidifyString, stringifyCid, createBlock, getBlockValue, calculateRawCid, checkDecodeBlock, verifyBlockBytes, codecCodes, defaultHasher, codecMap, } from "./block.js";
 //# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAc,MAAM,oBAAoB,CAAC;AAgEhD,OAAO,EACN,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,UAAU,EACV,aAAa,EACb,QAAQ,GACR,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAc,MAAM,oBAAoB,CAAC;AAsDhD,MAAM,CAAC,MAAM,0BAA0B,GAAqB,MAAM,CAAC,MAAM,CAAC;IACzE,eAAe,EAAE,SAAS;IAC1B,mBAAmB,EAAE,MAAM;CAC3B,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,gCAAgC,GAAqB,MAAM,CAAC,MAAM,CAC9E;IACC,eAAe,EAAE,eAAe;IAChC,mBAAmB,EAAE,MAAM;CAC3B,CACD,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CACxC,KAAc,EACK,EAAE;IACrB,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,0BAA0B,CAAC;IAC3D,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACjD,MAAM,IAAI,SAAS,CAAC,qCAAqC,CAAC,CAAC;IAC5D,CAAC;IACD,MAAM,eAAe,GAAI,KAAuC;SAC9D,eAAe,CAAC;IAClB,MAAM,mBAAmB,GAAI,KAA2C;SACtE,mBAAmB,CAAC;IACtB,IACC,eAAe,KAAK,eAAe;QACnC,eAAe,KAAK,kBAAkB;QACtC,eAAe,KAAK,QAAQ;QAC5B,eAAe,KAAK,SAAS,EAC5B,CAAC;QACF,MAAM,IAAI,SAAS,CAAC,sCAAsC,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,mBAAmB,KAAK,MAAM,EAAE,CAAC;QACpC,MAAM,IAAI,SAAS,CAAC,gDAAgD,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,eAAe,EAAE,mBAAmB,EAAE,CAAC,CAAC;AAChE,CAAC,CAAC;AAiDF,OAAO,EACN,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,UAAU,EACV,aAAa,EACb,QAAQ,GACR,MAAM,YAAY,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peerbit/blocks-interface",
-  "version": "2.1.7",
+  "version": "2.1.8",
   "description": "Block store streaming",
   "type": "module",
   "sideEffects": false,

package/src/index.ts

@@ -22,7 +22,87 @@ export type CrashSafeBlockDurability = {
 	barrier(): MaybePromise<void>;
 };
 
+/**
+ * Scope across which local references to a content-addressed block may alias.
+ *
+ * `block-service` is the scope of Peerbit's built-in stores: the backing
+ * namespace belongs to one blocks service, but every program using that
+ * service shares it. `caller-exclusive` is an explicit assertion that the
+ * declaring caller controls the entire physical namespace and every reference
+ * in it. `shared` means references may exist outside this block service;
+ * `unknown` makes no reliable scope assertion. Neither persistence nor a
+ * backend class implies any scope.
+ */
+export type BlockStoreReferenceDomain =
+	| "block-service"
+	| "caller-exclusive"
+	| "shared"
+	| "unknown";
+
+/**
+ * Immutable facts needed before a caller considers physical block deletion.
+ *
+ * `enforcedReclamation: "none"` means the store exposes no reference-safe
+ * lease, fencing, atomic delete-if-unreferenced, or isolated-namespace
+ * primitive. A raw `rm` is therefore safe only for an authority that controls
+ * the complete reference domain. This field is deliberately separate from
+ * `persisted()`.
+ */
+export type BlockStoreSafety = Readonly<{
+	referenceDomain: BlockStoreReferenceDomain;
+	enforcedReclamation: "none";
+}>;
+
+export const UNKNOWN_BLOCK_STORE_SAFETY: BlockStoreSafety = Object.freeze({
+	referenceDomain: "unknown",
+	enforcedReclamation: "none",
+});
+
+export const BLOCK_SERVICE_BLOCK_STORE_SAFETY: BlockStoreSafety = Object.freeze(
+	{
+		referenceDomain: "block-service",
+		enforcedReclamation: "none",
+	},
+);
+
+/**
+ * Validate, defensively copy, and freeze block-store safety metadata.
+ *
+ * The input is intentionally `unknown`: declarations can cross JavaScript and
+ * configuration boundaries where TypeScript's static shape is unavailable.
+ */
+export const normalizeBlockStoreSafety = (
+	value: unknown,
+): BlockStoreSafety => {
+	if (value === undefined) return UNKNOWN_BLOCK_STORE_SAFETY;
+	if (value === null || typeof value !== "object") {
+		throw new TypeError("Invalid block-store safety metadata");
+	}
+	const referenceDomain = (value as { referenceDomain?: unknown })
+		.referenceDomain;
+	const enforcedReclamation = (value as { enforcedReclamation?: unknown })
+		.enforcedReclamation;
+	if (
+		referenceDomain !== "block-service" &&
+		referenceDomain !== "caller-exclusive" &&
+		referenceDomain !== "shared" &&
+		referenceDomain !== "unknown"
+	) {
+		throw new TypeError("Invalid block-store reference domain");
+	}
+	if (enforcedReclamation !== "none") {
+		throw new TypeError("Unsupported block-store reclamation capability");
+	}
+	return Object.freeze({ referenceDomain, enforcedReclamation });
+};
+
 export interface Blocks extends WaitForPeer {
+	/**
+	 * Safety metadata for this service's local physical block namespace.
+	 * Absence is equivalent to {@link UNKNOWN_BLOCK_STORE_SAFETY} so older and
+	 * custom implementations fail closed.
+	 */
+	readonly localStoreSafety?: BlockStoreSafety;
 	put(
 		data: Uint8Array | { block: Block<any, any, any, any>; cid: string },
 	): MaybePromise<string>;