npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@inventarch/db

v3.8.0

Published

[![npm](https://img.shields.io/npm/v/@inventarch/db?label=npm)](https://www.npmjs.com/package/@inventarch/db) [![Public quality](https://github.com/inventarch/ia/actions/workflows/platform-quality.yml/badge.svg?branch=main)](https://github.com/inventarch/

Readme

@inventarch/db

npm Public quality License Node

@inventarch/db reads an IA workspace from disk. It discovers the workspace's .ia/src sources, installed distributions and adopted mounts, admits them through @inventarch/language, @inventarch/graph and @inventarch/compliance, and serves the admitted records through scoped read handles. @inventarch/runtime, the ia CLI and the other IA apps read workspaces through it.

⚡ Quick start

npm install @inventarch/db

Read the workspace from the root README quick start without writing to it:

import { open } from '@inventarch/db';

const workspace = open('path/to/your-project', { cache: false });
try {
  const { token } = workspace.resolveScope();
  const decision = workspace.get('work-system/definition/decision/api-response-format', { within: token });
  console.log(decision.band, decision.source.path);
  console.log(workspace.resolveSeat('.ia/src/decision.ia', { within: token }));
} finally {
  workspace.close();
}
100 .ia/src/decision.ia
{
  path: '.ia/src/decision.ia',
  seat: 'workspace-system/definition/workspace/my-project',
  by: 'root',
  claimants: []
}

open admits the workspace once. resolveScope issues an opaque token, and every read that passes it as within stays inside that scope. A handle holds the 4,096 ordinary scopes most recently issued or read, so a token left unread past that refuses with IA-DB-STALE, as one does once its sources change: issue a new scope. A scope issued with pinned: true sits outside that bound and stays until the sources change or the handle closes. Only a host holding the handle can pin, and nothing limits how many it does, so pin only what you can count. Band 100 marks a record the workspace authors. cache: false makes the open fully read-only. Without it, the handle keeps a disposable graph cache at .ia/.iadb/graph.json; a handle opened with checks: 'structural' or evidence: true never reads or writes that cache. The .ia/.gitignore that ia init writes does not list .iadb/, so add it to your ignore file.

🧭 What it does

| Export | Use it for | | --- | --- | | open(root, options) | Discover and admit a workspace and return a Handle. checks: 'structural' admits @check records the way ia validate, ia preview and ia author do. evidence: true also reads the evidence recorded for the current authored revision, at runtime placement (band 0). conformance: 'verify' verifies COMP-KERNEL and COMP-FIXTURES in-process; the editor readers take it too. adopted, authoredRoots, floor and locations replace discovered inputs; see SPEC.md. | | resolveScope(request) | Issue a scope token for a root, a phase or a list of identities. A child scope only narrows. | | get, records, snapshot, search, traverse, resolve, referencedBy, directedView | Read admitted records and their relationships through a token. | | resolveSeat, roots, words | Find the seat a path is declared at and the records that claim it, the declared source roots, and the registered words. | | report, refused, unadmitted | Admission findings and the records admission left out, for privileged host inspection. | | revision, authoredRevision, staleness, readiness, refresh() | Track change. The authored revision leaves out runtime-placed sources such as ia validate evidence; staleness and readiness compare a record with the previous retained snapshot. | | preview(changes) | Admit in-memory drafts against the current sources without writing anything. | | planCapture, writeCapture | Plan or write the capture pair under .ia/work/snapshot/ that ia capture maintains. | | bindChecks, writeEvidence, readEvidence | Bind each @check to an evaluator and keep the @observation evidence ia validate records under .ia/work/evidence/. | | writeRunnerEvidence | Record a verified runner journal under .ia/work/runner-evidence/. | | readWorkspaceBytes(root, path, limit) | Read one workspace file's exact bytes, refusing links, escaping paths and files over the limit. | | DbError, DB_CODES | Every operational refusal is a DbError. Its code is one of the eleven IA-DB-* codes in DB_CODES, and its optional path names the workspace-relative entry at fault. An installation refusal is an InstallationError from @inventarch/db/distribution, a DbError that adds a reason. A readWorkspaceBytes limit or a capture text of the wrong form is a TypeError. | | @inventarch/db/editor | EditorDatabase and EditorSnapshot: cache-free readers with unsaved overlay buffers. | | @inventarch/db/distribution | Strict decoders and canonical bytes for release descriptors, manifests, locks, generation membership, activation pointers and the installed-implementation catalog, and readInstalledGeneration, which verifies the active installed generation. | | @inventarch/db/descriptors | Pure, bounded compilers for domain-model, storage-binding and app-composition descriptor resources; see their contract. |

When you record validation evidence (bindChecks, then writeEvidence), bind the checks from a report without verification: verification changes the COMP-KERNEL and COMP-FIXTURES verdicts, and every reader admits evidence only as an unverified report binds it. EditorSnapshot.inspect() returns a View carrying both: report, verified when asked, and unverified, the report without verification. A Handle exposes only report, so record from a handle opened without conformance: 'verify' and use a second, verifying handle for display, requiring matching authoredRevision values before combining their results and reading again if the workspace changed between reads.

The ./internal/* subpaths serve specific toolchain consumers and are not a stable contract.

⚖️ What it does not do

  • It never writes authored source. Its only writes are the disposable cache, which cache: false turns off, and the capture pair and evidence files, each only when you call its writer.
  • It makes no network request and no installation write. Reads verify installed distributions and refuse missing, corrupt or drifted state. Acquiring and installing archives belongs to the application, such as the ia CLI.
  • Admission is not evaluation. Opening a workspace runs no conformance suite unless you pass conformance: 'verify', which runs @inventarch/compliance's package profile in the same process, and never a prose case. bindChecks runs no evaluator that is not built in: such a check stays not-evaluated, which is never a pass.
  • A scope narrows reads; it does not decide who reads. Unscoped reads and issuing independent scopes are privileged host inspection, and the host that holds the handle decides what it discloses. Call isCompleteScope(token) before you show report, refused or unadmitted to a reader: only a whole-workspace scope may disclose them.
  • Evidence is not attestation. A runner journal's hash chain establishes internal integrity, not an external observer, authorized execution or real-world effects.

📚 Learn more