@aigne/afs-did-space 1.12.0-beta.5

package/dist/tree-index.cjs

@@ -0,0 +1,333 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+let _aigne_afs = require("@aigne/afs");
+
+//#region src/tree-index.ts
+/**
+* TreeIndex — typed interface for file metadata indexing.
+*
+* Replaces KeyValueStore for DID Space tree entries.
+* Implementations: MemoryTreeIndex (testing), D1TreeIndex (production).
+*/
+const log = (0, _aigne_afs.makeNsLog)("provider:did-space");
+/**
+* Stable code on a per-scope quota rejection (file-count OR byte quota,
+* upload-limits Phase 5 / T5.2). Surfaced via the thrown Error's `.code`
+* (single-put/delete) and the batch result entry's `.code` (batchPut) so a
+* consumer can distinguish quota from other failures — previously these were
+* message-only. The message text is preserved verbatim for parity.
+*/
+const STORAGE_QUOTA_EXCEEDED_CODE = "STORAGE_QUOTA_EXCEEDED";
+/** Build a quota-rejection Error carrying {@link STORAGE_QUOTA_EXCEEDED_CODE}. */
+function storageQuotaError(message) {
+	return Object.assign(new Error(message), { code: STORAGE_QUOTA_EXCEEDED_CODE });
+}
+/**
+* Parse a raw `entries.metadata` column value back into an object.
+*
+* Contract:
+* - NULL / empty / non-string → undefined (no metadata)
+* - valid JSON object → that object
+* - parse error or non-object JSON → undefined + console.warn (best-effort:
+*   one bad row must not break list/read of the whole collection)
+*/
+function parseTreeEntryMetadata(raw) {
+	if (raw == null) return void 0;
+	if (typeof raw !== "string" || raw.length === 0) return void 0;
+	try {
+		const parsed = JSON.parse(raw);
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+		log.warn(`[did-space] entries.metadata is not a JSON object; treating as empty`);
+		return;
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		log.warn(`[did-space] failed to parse entries.metadata (${msg}); treating as empty`);
+		return;
+	}
+}
+/**
+* Serialize a TreeEntry.metadata object for storage in the
+* `entries.metadata` column.
+*
+* Contract:
+* - undefined / null / empty object → null (don't waste a JSON literal)
+* - non-empty object → JSON.stringify result
+*/
+function serializeTreeEntryMetadata(metadata) {
+	if (metadata == null) return null;
+	if (Object.keys(metadata).length === 0) return null;
+	return JSON.stringify(metadata);
+}
+/** Order-insensitive deep equality: object keys are unordered, array order matters. */
+function deepEqual(a, b) {
+	if (a === b) return true;
+	if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return false;
+	const aArr = Array.isArray(a);
+	const bArr = Array.isArray(b);
+	if (aArr !== bArr) return false;
+	if (aArr && bArr) {
+		if (a.length !== b.length) return false;
+		for (let i = 0; i < a.length; i++) if (!deepEqual(a[i], b[i])) return false;
+		return true;
+	}
+	const ao = a;
+	const bo = b;
+	const ak = Object.keys(ao);
+	if (ak.length !== Object.keys(bo).length) return false;
+	for (const k of ak) {
+		if (!Object.hasOwn(bo, k)) return false;
+		if (!deepEqual(ao[k], bo[k])) return false;
+	}
+	return true;
+}
+/**
+* Are two TreeEntry.metadata objects equivalent for skip-if-unchanged purposes?
+* (did-space-metadata G4). This MUST be order-insensitive for object keys —
+* {@link serializeTreeEntryMetadata} is a bare `JSON.stringify` that preserves
+* insertion order, so its string equality would treat a key reorder as a
+* "change" and forge a phantom changelog row / sync churn (the very thing skip
+* exists to avoid). Empty / null / undefined all compare equal because they all
+* serialize to a NULL column. Used ONLY for the skip decision; storage still
+* uses {@link serializeTreeEntryMetadata} verbatim.
+*/
+function treeEntryMetadataEqual(a, b) {
+	const aEmpty = a == null || Object.keys(a).length === 0;
+	const bEmpty = b == null || Object.keys(b).length === 0;
+	if (aEmpty || bEmpty) return aEmpty && bEmpty;
+	return deepEqual(a, b);
+}
+/** UTF-8 safe base64 (btoa alone corrupts non-latin1 file names). */
+function b64encode(s) {
+	const bytes = new TextEncoder().encode(s);
+	let bin = "";
+	for (const b of bytes) bin += String.fromCharCode(b);
+	return btoa(bin);
+}
+function b64decode(s) {
+	const bin = atob(s);
+	return new TextDecoder().decode(Uint8Array.from(bin, (c) => c.charCodeAt(0)));
+}
+/** Build a v2 keyset cursor: `v2:<b64(json(sortValue))>:<b64(tie)>`. */
+function buildKeysetCursor(sortValue, tie) {
+	return `v2:${b64encode(JSON.stringify(sortValue))}:${b64encode(tie)}`;
+}
+/**
+* Parse a list cursor. Shared by all three TreeIndex impls so the
+* legacy-vs-v2 dance can never drift between them.
+*
+* - undefined → none
+* - `v2:`-prefixed → keyset cursor; REQUIRES `hasOrderBy` (a keyset cursor
+*   replayed onto a default-order listing would be a wrong page); malformed
+*   payloads throw a clean error instead of producing a wrong page.
+* - anything else → legacy plain cursor, accepted ONLY for default
+*   (no-orderBy) order.
+*/
+function parseTreeCursor(cursor, hasOrderBy) {
+	if (!cursor) return { kind: "none" };
+	if (cursor.startsWith("v2:")) {
+		if (!hasOrderBy) throw new Error("Invalid cursor: v2 keyset cursor requires a matching orderBy");
+		const parts = cursor.split(":");
+		if (parts.length !== 3 || !parts[1] || !parts[2]) throw new Error("Invalid cursor: malformed v2 keyset cursor");
+		let sortValue;
+		let tie;
+		try {
+			sortValue = JSON.parse(b64decode(parts[1]));
+			tie = b64decode(parts[2]);
+		} catch {
+			throw new Error("Invalid cursor: malformed v2 keyset cursor");
+		}
+		if (sortValue !== null && typeof sortValue !== "string" && typeof sortValue !== "number") throw new Error("Invalid cursor: malformed v2 keyset cursor");
+		return {
+			kind: "v2",
+			cursor: {
+				sortValue,
+				tie
+			}
+		};
+	}
+	if (hasOrderBy) throw new Error("Invalid cursor: legacy cursor cannot be combined with orderBy");
+	return {
+		kind: "legacy",
+		value: cursor
+	};
+}
+/**
+* Build the ORDER BY + keyset-resume WHERE for an ordered listing. Shared
+* by SQLiteTreeIndex and D1TreeIndex (identical SQL dialect).
+*
+* - Missing values sort LAST regardless of direction: nullable columns get
+*   a leading `(col IS NULL) ASC` term. Non-nullable columns skip it so the
+*   `(scope, parent, col, name)` indexes stay usable.
+* - Resume uses the expansion `col > ? OR (col = ? AND tie > ?)` (row-value
+*   free — works on every SQLite the runtimes target) plus NULL-run
+*   handling for nullable columns.
+*/
+function buildOrderedQueryParts(opts) {
+	const { col, nullable, tieCol, cursor } = opts;
+	const dir = opts.order === "desc" ? "DESC" : "ASC";
+	const op = opts.order === "desc" ? "<" : ">";
+	const orderSql = nullable ? `(${col} IS NULL) ASC, ${col} ${dir}, ${tieCol} ${dir}` : `${col} ${dir}, ${tieCol} ${dir}`;
+	if (!cursor) return {
+		cursorWhereSql: "",
+		cursorArgs: [],
+		orderSql
+	};
+	if (cursor.sortValue === null) {
+		if (!nullable) throw new Error("Invalid cursor: malformed v2 keyset cursor");
+		return {
+			cursorWhereSql: `(${col} IS NULL AND ${tieCol} ${op} ?)`,
+			cursorArgs: [cursor.tie],
+			orderSql
+		};
+	}
+	if (nullable) return {
+		cursorWhereSql: `((${col} IS NOT NULL AND (${col} ${op} ? OR (${col} = ? AND ${tieCol} ${op} ?))) OR ${col} IS NULL)`,
+		cursorArgs: [
+			cursor.sortValue,
+			cursor.sortValue,
+			cursor.tie
+		],
+		orderSql
+	};
+	return {
+		cursorWhereSql: `(${col} ${op} ? OR (${col} = ? AND ${tieCol} ${op} ?))`,
+		cursorArgs: [
+			cursor.sortValue,
+			cursor.sortValue,
+			cursor.tie
+		],
+		orderSql
+	};
+}
+/**
+* In-memory equivalents of the SQL ordering semantics, used by
+* MemoryTreeIndex so all three impls stay in lockstep.
+*/
+function compareTreeSortValues(a, b, order) {
+	if (a === null && b === null) return 0;
+	if (a === null) return 1;
+	if (b === null) return -1;
+	let cmp;
+	if (typeof a === "number" && typeof b === "number") cmp = a === b ? 0 : a < b ? -1 : 1;
+	else {
+		const as = String(a);
+		const bs = String(b);
+		cmp = as === bs ? 0 : as < bs ? -1 : 1;
+	}
+	return order === "desc" ? -cmp : cmp;
+}
+/** Keyset predicate mirroring {@link buildOrderedQueryParts}'s WHERE. */
+function keysetAfter(rowSort, rowTie, cursor, order) {
+	const tieAfter = order === "desc" ? rowTie < cursor.tie : rowTie > cursor.tie;
+	if (cursor.sortValue === null) return rowSort === null && tieAfter;
+	if (rowSort === null) return true;
+	const cmp = compareTreeSortValues(rowSort, cursor.sortValue, order);
+	if (cmp !== 0) return cmp > 0;
+	return tieAfter;
+}
+/**
+* Loop reference implementation of `batchPutEntries` — single-op semantics
+* per entry, in order. SQLite/memory indexes delegate here (semantic
+* equivalence with the merged D1 path is pinned by conformance).
+*/
+async function loopBatchPutEntries(index, entries, ctx) {
+	const results = [];
+	for (const { path, entry, opts } of entries) {
+		const existing = ctx?.preread?.has(path) ? ctx.preread.get(path) ?? null : await index.get(path);
+		if (opts.ifMatch !== void 0 && (!existing || existing.cid !== opts.ifMatch)) {
+			results.push({
+				path,
+				conflict: {
+					currentCid: existing?.cid ?? null,
+					currentMtime: existing?.mtime ?? null,
+					currentDeviceId: null
+				}
+			});
+			continue;
+		}
+		if (existing && existing.cid === entry.cid && existing.mimeType === entry.mimeType && treeEntryMetadataEqual(existing.metadata, entry.metadata)) {
+			const wouldBeInline = index.inlineForEntry ? await index.inlineForEntry(entry) : void 0;
+			if (wouldBeInline === void 0 || (existing.content ?? null) === wouldBeInline) {
+				results.push({
+					path,
+					oldCid: existing.cid,
+					skipped: true
+				});
+				continue;
+			}
+		}
+		try {
+			const { oldCid } = await index.put(path, entry, { deviceId: opts.deviceId });
+			const liveSeq = await index.getPrefixWatermark?.(path) ?? void 0;
+			results.push({
+				path,
+				...oldCid !== void 0 ? { oldCid } : {},
+				...typeof liveSeq === "number" && liveSeq > 0 ? { liveSeq } : {}
+			});
+		} catch (err) {
+			const code = err?.code;
+			results.push({
+				path,
+				error: err instanceof Error ? err.message : String(err),
+				...typeof code === "string" ? { code } : {}
+			});
+		}
+	}
+	return results;
+}
+/** Loop reference implementation of `batchDeleteEntries` — see {@link loopBatchPutEntries}. */
+async function loopBatchDeleteEntries(index, entries, ctx) {
+	const results = [];
+	for (const { path, opts } of entries) {
+		const existing = ctx?.preread?.has(path) ? ctx.preread.get(path) ?? null : await index.get(path);
+		if (opts.ifMatch !== void 0 && (!existing || existing.cid !== opts.ifMatch)) {
+			results.push({
+				path,
+				conflict: {
+					currentCid: existing?.cid ?? null,
+					currentMtime: existing?.mtime ?? null,
+					currentDeviceId: null
+				}
+			});
+			continue;
+		}
+		if (!existing) {
+			results.push({
+				path,
+				notFound: true
+			});
+			continue;
+		}
+		try {
+			await index.delete(path, {
+				deviceId: opts.deviceId,
+				...opts.mtime !== void 0 ? { mtime: opts.mtime } : {}
+			});
+			const liveSeq = await index.getPrefixWatermark?.(path) ?? void 0;
+			results.push({
+				path,
+				deletedCid: existing.cid,
+				...typeof liveSeq === "number" && liveSeq > 0 ? { liveSeq } : {}
+			});
+		} catch (err) {
+			results.push({
+				path,
+				error: err instanceof Error ? err.message : String(err)
+			});
+		}
+	}
+	return results;
+}
+
+//#endregion
+exports.STORAGE_QUOTA_EXCEEDED_CODE = STORAGE_QUOTA_EXCEEDED_CODE;
+exports.buildKeysetCursor = buildKeysetCursor;
+exports.buildOrderedQueryParts = buildOrderedQueryParts;
+exports.compareTreeSortValues = compareTreeSortValues;
+exports.keysetAfter = keysetAfter;
+exports.loopBatchDeleteEntries = loopBatchDeleteEntries;
+exports.loopBatchPutEntries = loopBatchPutEntries;
+exports.parseTreeCursor = parseTreeCursor;
+exports.parseTreeEntryMetadata = parseTreeEntryMetadata;
+exports.serializeTreeEntryMetadata = serializeTreeEntryMetadata;
+exports.storageQuotaError = storageQuotaError;
+exports.treeEntryMetadataEqual = treeEntryMetadataEqual;