DBOPFS

DBOPFS is a browser-native database built directly on the Origin Private File System. Tables are directories, records are files, and application data stays in the browser unless the application exports it.

This 1.0.0 package preserves the production ARCANE OS runtime byte-for-byte. Its surrounding package, release tests, coverage evidence, licensing, and documentation are new; the three implementation files are unchanged.

Read the documentation · Inspect with the Studio Extension · Open the playground · Review release evidence

npm install [email protected]

Expose the complete node_modules/dbopfs/ directory through your web server at /vendor/dbopfs/.

Download the verified dbopfs-1.0.0.tgz release asset, then extract its top-level package/ directory as vendor/dbopfs/ in your web project.

# macOS, Linux, Git Bash, or WSL
curl -fL https://github.com/TheWizardNexus/DBOPFS/releases/download/v1.0.0/dbopfs-1.0.0.tgz -o dbopfs-1.0.0.tgz
mkdir -p vendor/dbopfs
tar -xzf dbopfs-1.0.0.tgz -C vendor/dbopfs --strip-components=1

# PowerShell
Invoke-WebRequest 'https://github.com/TheWizardNexus/DBOPFS/releases/download/v1.0.0/dbopfs-1.0.0.tgz' -OutFile 'dbopfs-1.0.0.tgz'
New-Item -ItemType Directory -Force 'vendor/dbopfs' | Out-Null
tar -xzf 'dbopfs-1.0.0.tgz' -C 'vendor/dbopfs' --strip-components=1

The v1.0.0 release page includes release notes, checksums, and verification evidence. Both installation paths provide the same package layout.

DBOPFS is a browser-only ESM module. Serve it over HTTPS or localhost; do not import it during Node.js server-side rendering.

Declare a stable application ID before loading the module:

<meta name="arcane-app-id" content="my-app">
<script type="module">
  import '/vendor/dbopfs/arcane/modules/DBOPFS.js';

  await window.dbopfs.readyPromise;

  await window.dbopfs.set('users', 'alex.json', {
    email: '[email protected]',
    role: 'admin'
  });

  const alex = await window.dbopfs.get('users', 'alex.json');
  console.log(alex);
</script>

With a browser-aware bundler or import map, the package root exports the same default DBOPFS class:

import DBOPFS from 'dbopfs';

const db = window.dbopfs || new DBOPFS({applicationId: 'my-app'});
await db.readyPromise;

Use a .json key when you want get() to parse an object. Plain-text keys return strings; .jsonl and .ndjson keys return parsed row arrays.

DBOPFS Studio is a Chromium extension for exploring and managing an origin's DBOPFS applications, tables, and records. Open it from the browser toolbar to connect Studio to the current site, or open DevTools (the Console), select the dedicated DBOPFS Studio panel, and choose Open Studio window to connect it to the inspected page.

The extension is currently installed from source as an unpacked build. Follow the DBOPFS Studio Extension guide for installation, both connection paths, origin boundaries, and troubleshooting.

OPFS root/
└── apps/
    └── my-app/
        ├── users/
        │   └── alex.json
        ├── documents/
        └── memory/

An application ID stores records under apps/<application-id>. This helps prevent accidental reads, restores, or clears between trusted apps that share one browser origin (the same protocol, host, and port). Common examples are test apps at example.com/app-a and example.com/app-b, or several apps served from one intranet or extranet host without subdomains.

The folder is an organizational boundary, not a security boundary. A hostile or compromised script running on the same origin can bypass DBOPFS and request the browser's raw storage APIs. If applications do not trust one another or require isolated databases, host them on separate origins—normally separate domains or subdomains—or run them in separate browser profiles.

Trusted apps can deliberately share a browser-local database by using the same application ID and agreeing on the same tables and data formats. An app can also download validated seed data from a server and write it locally, or implement authenticated synchronization across browsers, devices, and machines. DBOPFS 1.0.0 does not provide the server, authentication, authorization, encryption, conflict handling, or sync protocol; those parts must be built for the application's security needs. Built-in preload or synchronization support may be considered in a future release if there is enough interest.

Arcane OS already supports DBOPFS database export/import and packaged database prepopulation. See the application-scoping architecture guide for diagrams and deployment guidance.

The race-safe path is the singleton promise:

await window.dbopfs.readyPromise;

The module also dispatches dbopfs-ready with {dbopfs, applicationId, storagePath}:

window.addEventListener('dbopfs-ready', ({detail}) => {
  console.log(detail.applicationId, detail.storagePath);
});

The API reference documents signatures, return values, cache behavior, and existing error semantics.

The tables property is a page-local in-memory cache: it belongs only to the current loaded page, is not durable storage, and is not automatically refreshed when another tab or script changes OPFS. Read the cache guide before relying on cached reads.

Storage methods are asynchronous and return promises. The async patterns guide explains when to await immediately, when to start independent work and await it later, and why await gives sequencing rather than a multi-record transaction.

Both npm and the GitHub Release provide this layout. Expose the selected package root at a stable web path such as /vendor/dbopfs/:

/vendor/dbopfs/
├── arcane/modules/
│   ├── AppDataScope.js
│   ├── DBOPFS.js
│   └── DBOPFSWorker.js
└── node_modules/strong-type/

An ARCANE installation can redirect its DBOPFS module mount or import pointer from the in-tree arcane/modules source to the selected package root's arcane/modules directory. That package root can be an npm installation or the extracted GitHub Release. The worker and application-scope module remain adjacent, and the relative strong-type import remains valid because that dependency is bundled. Existing DBOPFS call sites do not need API changes.

The release test installs the packed tarball into a clean consumer fixture and verifies this exact layout before publication.

Release tests use [email protected] in Google Chrome against real OPFS on localhost. The test toolchain requires Node.js 22.12 or newer; this does not change the browser runtime requirements for DBOPFS itself. The current evidence contains 87 unique cases across Unit (37), Functional (34), Integration (12), and Regression (4) suites. Chrome precise coverage is captured for the three runtime modules. Release tests do not run in GitHub Actions; the repository's Pages-only workflow deploys the documentation. Badges are generated from the final release evidence committed under release/.

npm ci
npm run release:test

• Requires a secure context and navigator.storage.getDirectory().
• Uses a dedicated worker when synchronous OPFS access is needed.
• Requests persistent storage when the browser supports it; the browser may decline.
• Browser storage quotas, eviction rules, and backup APIs vary by browser.
• Importing in Node.js or SSR without browser globals is unsupported.
• Existing implementation behavior is documented rather than silently changed for 1.0.0.

Noncommercial use is licensed under PolyForm Noncommercial 1.0.0. This is source-available software, not OSI open source.

A separate paid commercial license is available for a nominal fee; see COMMERCIAL-LICENSE.md. Downloading the package does not grant commercial rights.

Redistributors must preserve the license terms or official license URL and every exact Required Notice: line in NOTICE, as required by PolyForm's Notices clause.

Source identity and hashes are recorded in SOURCE_PROVENANCE.md. Third-party terms are listed in THIRD_PARTY_NOTICES.md.