@sqlite.org/sqlite-wasm - npm Package Compare versions

Comparing version 3.51.2-build6 to 3.51.2-build7

dist/sqlite3-opfs-async-proxy.js

 "use strict";
 (function() {
+	//#region src/bin/sqlite3-opfs-async-proxy.js
 	/* @preserve
@@ -64,3 +65,15 @@ 2022-09-16
 		else if (!navigator?.storage?.getDirectory) toss("This API requires navigator.storage.getDirectory.");
+		/**
+		Will hold state copied to this object from the synchronous side of
+		this API.
+		*/
 		const state = Object.create(null);
+		/**
+		verbose:
+		
+		0 = no logging output
+		1 = only errors
+		2 = warnings and errors
+		3 = debug, warnings, and errors
+		*/
 		state.verbose = 1;
@@ -78,4 +91,30 @@ const loggers = {
 		const error = (...args) => logImpl(0, ...args);
+		/**
+		__openFiles is a map of sqlite3_file pointers (integers) to
+		metadata related to a given OPFS file handles. The pointers are, in
+		this side of the interface, opaque file handle IDs provided by the
+		synchronous part of this constellation. Each value is an object
+		with a structure demonstrated in the xOpen() impl.
+		*/
 		const __openFiles = Object.create(null);
+		/**
+		__implicitLocks is a Set of sqlite3_file pointers (integers) which were
+		"auto-locked".  i.e. those for which we obtained a sync access
+		handle without an explicit xLock() call. Such locks will be
+		released during db connection idle time, whereas a sync access
+		handle obtained via xLock(), or subsequently xLock()'d after
+		auto-acquisition, will not be released until xUnlock() is called.
+		
+		Maintenance reminder: if we relinquish auto-locks at the end of the
+		operation which acquires them, we pay a massive performance
+		penalty: speedtest1 benchmarks take up to 4x as long. By delaying
+		the lock release until idle time, the hit is negligible.
+		*/
 		const __implicitLocks = /* @__PURE__ */ new Set();
+		/**
+		Expects an OPFS file path. It gets resolved, such that ".."
+		components are properly expanded, and returned. If the 2nd arg is
+		true, the result is returned as an array of path elements, else an
+		absolute path string is returned.
+		*/
 		const getResolvedPath = function(filename, splitIt) {
@@ -85,2 +124,8 @@ const p = new URL(filename, "file://irrelevant").pathname;
 		};
+		/**
+		Takes the absolute path to a filesystem element. Returns an array
+		of [handleOfContainingDir, filename]. If the 2nd argument is truthy
+		then each directory element leading to the file is created along
+		the way. Throws if any creation or resolution fails.
+		*/
 		const getDirForFilename = async function f(absFilename, createDirs = false) {
@@ -93,2 +138,12 @@ const path = getResolvedPath(absFilename, true);
 		};
+		/**
+		If the given file-holding object has a sync handle attached to it,
+		that handle is removed and asynchronously closed. Though it may
+		sound sensible to continue work as soon as the close() returns
+		(noting that it's asynchronous), doing so can cause operations
+		performed soon afterwards, e.g. a call to getSyncHandle(), to fail
+		because they may happen out of order from the close(). OPFS does
+		not guaranty that the actual order of operations is retained in
+		such cases. i.e.  always "await" on the result of this function.
+		*/
 		const closeSyncHandle = async (fh) => {
@@ -104,2 +159,13 @@ if (fh.syncHandle) {
 		};
+		/**
+		A proxy for closeSyncHandle() which is guaranteed to not throw.
+		
+		This function is part of a lock/unlock step in functions which
+		require a sync access handle but may be called without xLock()
+		having been called first. Such calls need to release that
+		handle to avoid locking the file for all of time. This is an
+		_attempt_ at reducing cross-tab contention but it may prove
+		to be more of a problem than a solution and may need to be
+		removed.
+		*/
 		const closeSyncHandleNoThrow = async (fh) => {
@@ -119,5 +185,31 @@ try {
 		};
+		/**
+		An experiment in improving concurrency by freeing up implicit locks
+		sooner. This is known to impact performance dramatically but it has
+		also shown to improve concurrency considerably.
+		
+		If fh.releaseImplicitLocks is truthy and fh is in __implicitLocks,
+		this routine returns closeSyncHandleNoThrow(), else it is a no-op.
+		*/
 		const releaseImplicitLock = async (fh) => {
 			if (fh.releaseImplicitLocks && __implicitLocks.has(fh.fid)) return closeSyncHandleNoThrow(fh);
 		};
+		/**
+		An error class specifically for use with getSyncHandle(), the goal
+		of which is to eventually be able to distinguish unambiguously
+		between locking-related failures and other types, noting that we
+		cannot currently do so because createSyncAccessHandle() does not
+		define its exceptions in the required level of detail.
+		
+		2022-11-29: according to:
+		
+		https://github.com/whatwg/fs/pull/21
+		
+		NoModificationAllowedError will be the standard exception thrown
+		when acquisition of a sync access handle fails due to a locking
+		error. As of this writing, that error type is not visible in the
+		dev console in Chrome v109, nor is it documented in MDN, but an
+		error with that "name" property is being thrown from the OPFS
+		layer.
+		*/
 		class GetSyncHandleError extends Error {
@@ -133,9 +225,46 @@ constructor(errorObject, ...msg) {
 		}
+		/**
+		Attempts to find a suitable SQLITE_xyz result code for Error
+		object e. Returns either such a translation or rc if if it does
+		not know how to translate the exception.
+		*/
 		GetSyncHandleError.convertRc = (e, rc) => {
 			if (e instanceof GetSyncHandleError) {
 				if (e.cause.name === "NoModificationAllowedError" || e.cause.name === "DOMException" && 0 === e.cause.message.indexOf("Access Handles cannot")) return state.sq3Codes.SQLITE_BUSY;
-				else if ("NotFoundError" === e.cause.name) return state.sq3Codes.SQLITE_CANTOPEN;
+				else if ("NotFoundError" === e.cause.name)
+ /**
+				Maintenance reminder: SQLITE_NOTFOUND, though it looks like
+				a good match, has different semantics than NotFoundError
+				and is not suitable here.
+				*/
+				return state.sq3Codes.SQLITE_CANTOPEN;
 			} else if ("NotFoundError" === e?.name) return state.sq3Codes.SQLITE_CANTOPEN;
 			return rc;
 		};
+		/**
+		Returns the sync access handle associated with the given file
+		handle object (which must be a valid handle object, as created by
+		xOpen()), lazily opening it if needed.
+		
+		In order to help alleviate cross-tab contention for a dabase, if
+		an exception is thrown while acquiring the handle, this routine
+		will wait briefly and try again, up to some fixed number of
+		times. If acquisition still fails at that point it will give up
+		and propagate the exception. Client-level code will see that as
+		an I/O error.
+		
+		2024-06-12: there is a rare race condition here which has been
+		reported a single time:
+		
+		https://sqlite.org/forum/forumpost/9ee7f5340802d600
+		
+		What appears to be happening is that file we're waiting for a
+		lock on is deleted while we wait. What currently happens here is
+		that a locking exception is thrown but the exception type is
+		NotFoundError. In such cases, we very probably should attempt to
+		re-open/re-create the file an obtain the lock on it (noting that
+		there's another race condition there). That's easy to say but
+		creating a viable test for that condition has proven challenging
+		so far.
+		*/
 		const getSyncHandle = async (fh, opName) => {
@@ -163,2 +292,6 @@ if (!fh.syncHandle) {
 		};
+		/**
+		Stores the given value at state.sabOPView[state.opIds.rc] and then
+		Atomics.notify()'s it.
+		*/
 		const storeAndNotify = (opName, value) => {
@@ -169,6 +302,19 @@ log(opName + "() => notify(", value, ")");
 		};
+		/**
+		Throws if fh is a file-holding object which is flagged as read-only.
+		*/
 		const affirmNotRO = function(opName, fh) {
 			if (fh.readOnly) toss(opName + "(): File is read-only: " + fh.filenameAbs);
 		};
+		/**
+		Gets set to true by the 'opfs-async-shutdown' command to quit the
+		wait loop. This is only intended for debugging purposes: we cannot
+		inspect this file's state while the tight waitLoop() is running and
+		need a way to stop that loop for introspection purposes.
+		*/
 		let flagAsyncShutdown = false;
+		/**
+		Asynchronous wrappers for sqlite3_vfs and sqlite3_io_methods
+		methods, as well as helpers like mkdir().
+		*/
 		const vfsAsyncImpls = {
@@ -373,2 +519,6 @@ "opfs-async-shutdown": async () => {
 		const initS11n = () => {
+			/**
+			ACHTUNG: this code is 100% duplicated in the other half of this
+			proxy! The documentation is maintained in the "synchronous half".
+			*/
 			if (state.s11n) return state.s11n;
@@ -525,2 +675,3 @@ const textDecoder = new TextDecoder(), textEncoder = new TextEncoder("utf-8"), viewU8 = new Uint8Array(state.sabIO, state.sabS11nOffset, state.sabS11nSize), viewDV = new DataView(state.sabIO, state.sabS11nOffset, state.sabS11nSize);
 	else installAsyncProxy();
+	//#endregion
 })();

package.json

 {
   "name": "@sqlite.org/sqlite-wasm",
-  "version": "3.51.2-build6",
+  "version": "3.51.2-build7",
   "description": "SQLite Wasm conveniently wrapped as an ES Module.",
@@ -53,3 +53,3 @@ "type": "module",
     "publint": "npx publint",
-    "check-types": "tsc",
+    "check-types": "tsgo",
     "build": "tsdown",
@@ -61,3 +61,3 @@ "start": "npx http-server --coop",
     "prepublishOnly": "npm run build && npm run fix && npm run publint && npm run check-types",
-    "deploy": "npm run prepublishOnly && git add . && git commit -am 'New release' && git push && npm publish"
+    "deploy": "npm run prepublishOnly && git add . && git commit -am 'New release' && git push && npm publish --tag=latest"
   },
@@ -68,13 +68,14 @@ "engines": {
   "devDependencies": {
-    "@types/node": "^25.1.0",
+    "@types/node": "^25.4.0",
+    "@typescript/native-preview": "^7.0.0-dev.20260309.1",
     "@vitest/browser": "^4.0.18",
     "@vitest/browser-playwright": "^4.0.18",
-    "happy-dom": "^20.4.0",
+    "happy-dom": "^20.8.3",
     "http-server": "github:vapier/http-server",
-    "lefthook": "2.0.16",
-    "playwright": "^1.58.0",
+    "lefthook": "2.1.3",
+    "playwright": "^1.58.2",
     "prettier": "^3.8.1",
     "prettier-plugin-jsdoc": "^1.8.0",
-    "publint": "^0.3.17",
-    "tsdown": "^0.20.1",
+    "publint": "^0.3.18",
+    "tsdown": "^0.21.1",
     "typescript": "^5.9.3",
@@ -81,0 +82,0 @@ "vitest": "^4.0.18"

No alert changes

Improved metrics

Total package byte prevSize

2805123

25.65%

Lines of code

42842

39%

Worsened metrics

Dev dependency count

14

7.69%

No dependency changes