defuss-db

library2.0.2jsnpmunverified

TypeScript-first, isomorphic database abstraction supporting multiple backends (IndexedDB via Dexie, SQLite/libSQL, MongoDB, JSONL). v2.0.2 is current stable. Schema-driven table definition with auto-indexing, unified CRUD, and a provider-agnostic aggregation pipeline (joins, grouping, sorting). Differentiators: single API across browser and Node.js, built-in upsert, unique indexes, and no ORM overhead. Monthly releases. Ships types. ESM-only, requires Node >=18.17.1.

database

npm install defuss-db

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DEFUSS-DB

defuss-db

databasejavascriptv2.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.

DefussTable

✓ import { DefussTable } from 'defuss-db'

✗ import { DefussTable } from 'defuss-db/client.js'

DefussTable is a core export from the main entry, not from client.js. This is a common mistake.

defineTable

✓ import { defineTable } from 'defuss-db'

✗ import defineTable from 'defuss-db'

defineTable is a named export, not a default export. ESM-only; no require() works.

DexieProvider

✓ import { DexieProvider } from 'defuss-db/client.js'

✗ import { DexieProvider } from 'defuss-db'

Provider classes are exported from provider-specific subpaths (client.js, server.js). The main export does not include providers.

DefussRecord

✓ import type { DefussRecord } from 'defuss-db'

✗ import { DefussRecord } from 'defuss-db'

DefussRecord is a TypeScript type/interface, not a runtime value. Use type-only import to avoid errors at runtime.

createAggregation

✓ import { createAggregation, sumBy } from 'defuss-db'

Aggregation helpers are exported from the main package, not a subpath.

Declares a User table with a unique email index, connects to Dexie (IndexedDB), inserts a record, and finds it by email.

import { DefussTable, defineTable, type DefussRecord } from 'defuss-db'; import { DexieProvider } from 'defuss-db/client.js'; interface User extends DefussRecord { name: string; email: string; age: number; } const userTable = defineTable<User>({ name: 'users', indexes: [{ name: 'email', source: 'email', unique: true }], }); const provider = new DexieProvider('AppDatabase'); await provider.connect(); const users = new DefussTable(provider, userTable); await users.init(); const id = await users.insert({ name: 'Alice', email: 'alice@example.com', age: 30 }); const result = await users.findOne({ email: 'alice@example.com' }); console.log(result);

Debug

Known issues

breakingv2.0.0 removed the provider-less default export. All providers must be explicitly imported from subpaths.

fix

Import providers from 'defuss-db/client.js' (DexieProvider) or 'defuss-db/server.js' (LibsqlProvider, MongoProvider, JsonlProvider) instead of using deprecated defaults.

affects: >=2.0.0

breakingv2.0.0 changed the aggregation API: createAggregation() replaces legacy aggregation methods. The base table alias is 'base' by default.

fix

Use createAggregation({ table: myTable, as: 'alias' }) instead of myTable.aggregate() if you need a custom alias. If not, myTable.aggregate() still works but defaults to 'base'.

affects: >=2.0.0

deprecatedDirect use of DexieProvider constructor with a string database name is deprecated; pass a Dexie instance or options object instead.

fix

Use `new DexieProvider(new Dexie('AppDatabase'))` or provide an options object: `new DexieProvider({ database: 'AppDatabase' })`.

affects: >=2.0.0 <3

gotchaDefussRecord must be extended for all entity interfaces; missing it causes TypeScript errors.

fix

Always write `interface User extends DefussRecord { ... }`.

affects: >=1.0.0

gotchaESM-only package: require() throws an error. Node.js must use 'type': 'module' in package.json or .mjs extensions.

fix

Use import syntax. If you need CommonJS, upgrade to Node 22+ and use dynamic import().

affects: >=2.0.0

Errors

Common errors & fixes

Cannot find module 'defuss-db/client.js' or its corresponding type declarations

Missing tsconfig resolution for subpath exports or using an older version where client.js didn't exist.

fix

Ensure defuss-db >=2.0.0 is installed. In tsconfig.json, set "moduleResolution": "node16" or "bundler". If using an older version, upgrade: `npm install defuss-db@latest`.

Property 'insert' does not exist on type 'DefussTable<...>'

Trying to call CRUD methods before calling init().

fix

Add `await users.init();` before any insert, find, update, or delete.

Argument of type '{ email: string; }' is not assignable to parameter of type 'DefussRecord'

Missing the `id` field in the filter while using TypeScript strict mode - DefussRecord requires an optional id? No, but the filter expects a partial entity that could include id. Actually more likely: the interface doesn't extend DefussRecord.

fix

Ensure your entity interface extends DefussRecord: `interface User extends DefussRecord { ... }`

Cannot use import statement outside a module

Using import in a CommonJS (.js with no type:module) file.

fix

Rename file to .mjs, or add `"type": "module"` to package.json.

Upgrade

Version history

2.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/kyr0/defuss ↗

packagedefuss-db ↗

homepagehttps://github.com/kyr0/defuss#readme ↗