Registry / database / warp-contracts-sqlite

warp-contracts-sqlite

library1.0.2jsnpmunverified

An SQLite-based contract state cache for the Warp SDK (arweave smart contracts). Version 1.0.2 uses `better-sqlite3` for synchronous, fast I/O — differentiator vs the default LMDB cache or LevelDB alternatives. Released sporadically, peer dep on `warp-contracts` ^1.4.7. Ships TypeScript definitions. Common footgun: forgetting to call `close()` or assuming async initialization.

database storage

npm install warp-contracts-sqlite

package ↗

INSTALL

IMPORT

SIG · WARP-CONTRACTS-SQL

warp-contracts-sqlite

databasejavascriptv1.0.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SqliteContractCache

✓ import { SqliteContractCache } from 'warp-contracts-sqlite'

✗ const SqliteContractCache = require('warp-contracts-sqlite').default

ESM-only; the package does not expose a CommonJS default export. The named export is directly available.

default

✓ import SqliteContractCache from 'warp-contracts-sqlite'

✗ const SqliteContractCache = require('warp-contracts-sqlite')

Default export is the class itself. Use named or default, both work in ESM.

DEFAULT_DB_PATH

✓ import { DEFAULT_DB_PATH } from 'warp-contracts-sqlite'

Named export for the default SQLite database path string.

Initializes a SQLite-backed contract cache, connects it to Warp, reads contract state, and safely closes the cache.

import { WarpFactory } from 'warp-contracts'; import { SqliteContractCache } from 'warp-contracts-sqlite'; import { connect } from '@permaweb/aoconnect'; async function main() { const cache = new SqliteContractCache({ dbPath: './cache.db' }); await cache.init(); // creates SQLite tables if not exist const warp = WarpFactory.forMainnet({ cache, // other options... }); const contract = warp.contract('CONTRACT_ID'); const { state } = await contract.readState(); console.log('Contract state:', state); cache.close(); // important: release SQLite connection } main().catch(console.error);

Debug

Known issues

gotchaCalling `readState()` multiple times without closing/resetting the cache may lead to stale reads.

fix

Use `cache.clear()` or initiate a new cache instance for each fresh evaluation.

affects: >=1.0.0

gotcha`better-sqlite3` uses synchronous API; do not use with async-heavy loops or event loop blocking.

fix

Consider wrapping in a worker thread or using the LMDB cache for concurrent access.

affects: >=1.0.0

breakingIn v1.0.0, the constructor required a `dbPath` option string; v1.0.1+ accepts an options object or string.

fix

Upgrade to v1.0.2 or pass `{ dbPath: '...' }` as the first argument.

affects: 1.0.0

deprecatedThe `init()` method is optional as of v1.0.1; tables are created lazily.

fix

Remove explicit `init()` call; still safe to keep.

affects: >=1.0.1

Errors

Common errors & fixes

Error: Cannot find module 'better-sqlite3'

Missing runtime dependency `better-sqlite3`.

fix

npm install better-sqlite3 (ensure build tools for native modules)

SqliteContractCache is not a constructor

Using CommonJS require on default export (which is not a default CJS export).

fix

Use ESM import: `import { SqliteContractCache } from 'warp-contracts-sqlite'`

TypeError: cache.close is not a function

Cache not initialized (init() not called or failed).

fix

Ensure `await cache.init()` completes before calling close().

SQLITE_MISUSE: Database handle is closed

Calling methods after `close()` has been called.

fix

Do not reuse a closed cache; create a new instance.

Upgrade

Version history

1.0.2latest on npm

Audit

Dependencies

better-sqlite3requiredProvides synchronous SQLite bindings used internally by the cache implementation.

warp-contractsoptionalPeer dependency; the cache plugs into Warp's contract loader system.

Agent activity

41 hits · last 30 days

node