{"id":44708,"library":"defuss-db","title":"defuss-db","description":"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.","status":"active","version":"2.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/kyr0/defuss","tags":["javascript","db","database","abstraction","dexie","libsql","mongodb","jsonl","typescript"],"install":[{"cmd":"npm install defuss-db","lang":"bash","label":"npm"},{"cmd":"yarn add defuss-db","lang":"bash","label":"yarn"},{"cmd":"pnpm add defuss-db","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"DefussTable is a core export from the main entry, not from client.js. This is a common mistake.","wrong":"import { DefussTable } from 'defuss-db/client.js'","symbol":"DefussTable","correct":"import { DefussTable } from 'defuss-db'"},{"note":"defineTable is a named export, not a default export. ESM-only; no require() works.","wrong":"import defineTable from 'defuss-db'","symbol":"defineTable","correct":"import { defineTable } from 'defuss-db'"},{"note":"Provider classes are exported from provider-specific subpaths (client.js, server.js). The main export does not include providers.","wrong":"import { DexieProvider } from 'defuss-db'","symbol":"DexieProvider","correct":"import { DexieProvider } from 'defuss-db/client.js'"},{"note":"DefussRecord is a TypeScript type/interface, not a runtime value. Use type-only import to avoid errors at runtime.","wrong":"import { DefussRecord } from 'defuss-db'","symbol":"DefussRecord","correct":"import type { DefussRecord } from 'defuss-db'"},{"note":"Aggregation helpers are exported from the main package, not a subpath.","wrong":null,"symbol":"createAggregation","correct":"import { createAggregation, sumBy } from 'defuss-db'"}],"quickstart":{"code":"import { DefussTable, defineTable, type DefussRecord } from 'defuss-db';\nimport { DexieProvider } from 'defuss-db/client.js';\n\ninterface User extends DefussRecord {\n  name: string;\n  email: string;\n  age: number;\n}\n\nconst userTable = defineTable<User>({\n  name: 'users',\n  indexes: [{ name: 'email', source: 'email', unique: true }],\n});\n\nconst provider = new DexieProvider('AppDatabase');\nawait provider.connect();\n\nconst users = new DefussTable(provider, userTable);\nawait users.init();\n\nconst id = await users.insert({ name: 'Alice', email: 'alice@example.com', age: 30 });\nconst result = await users.findOne({ email: 'alice@example.com' });\nconsole.log(result);","lang":"typescript","description":"Declares a User table with a unique email index, connects to Dexie (IndexedDB), inserts a record, and finds it by email."},"warnings":[{"fix":"Import providers from 'defuss-db/client.js' (DexieProvider) or 'defuss-db/server.js' (LibsqlProvider, MongoProvider, JsonlProvider) instead of using deprecated defaults.","message":"v2.0.0 removed the provider-less default export. All providers must be explicitly imported from subpaths.","severity":"breaking","affected_versions":">=2.0.0"},{"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'.","message":"v2.0.0 changed the aggregation API: createAggregation() replaces legacy aggregation methods. The base table alias is 'base' by default.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use `new DexieProvider(new Dexie('AppDatabase'))` or provide an options object: `new DexieProvider({ database: 'AppDatabase' })`.","message":"Direct use of DexieProvider constructor with a string database name is deprecated; pass a Dexie instance or options object instead.","severity":"deprecated","affected_versions":">=2.0.0 <3"},{"fix":"Always write `interface User extends DefussRecord { ... }`.","message":"DefussRecord must be extended for all entity interfaces; missing it causes TypeScript errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use import syntax. If you need CommonJS, upgrade to Node 22+ and use dynamic import().","message":"ESM-only package: require() throws an error. Node.js must use 'type': 'module' in package.json or .mjs extensions.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"search_vec":"'18.17.1':70 'abstract':9,74 'across':47 'aggreg':39 'agnost':38 'api':46 'auto':30 'auto-index':29 'backend':12 'browser':48 'built':52 'built-in':51 'crud':33 'current':21 'databas':8,73 'db':3,72 'definit':27 'defuss':2 'defuss-db':1 'dexi':15,75 'differenti':44 'driven':25 'esm':66 'esm-on':65 'first':6 'group':42 'index':31,56 'indexeddb':13 'isomorph':7 'javascript':71 'join':41 'jsonl':18,78 'libsql':76 'mongodb':17,77 'month':61 'multipl':11 'node':69 'node.js':50 'orm':59 'overhead':60 'pipelin':40 'provid':37 'provider-agnost':36 'releas':62 'requir':68 'schema':24 'schema-driven':23 'ship':63 'singl':45 'sort':43 'sqlite/libsql':16 'stabl':22 'support':10 'tabl':26 'type':64 'typescript':5,79 'typescript-first':4 'unifi':32 'uniqu':55 'upsert':54 'v2.0.2':19 'via':14","created_at":"2026-06-07T12:51:27.158440+00:00","updated_at":"2026-06-07T12:51:27.158440+00:00","problems":[{"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`.","cause":"Missing tsconfig resolution for subpath exports or using an older version where client.js didn't exist.","error":"Cannot find module 'defuss-db/client.js' or its corresponding type declarations"},{"fix":"Add `await users.init();` before any insert, find, update, or delete.","cause":"Trying to call CRUD methods before calling init().","error":"Property 'insert' does not exist on type 'DefussTable<...>'"},{"fix":"Ensure your entity interface extends DefussRecord: `interface User extends DefussRecord { ... }`","cause":"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.","error":"Argument of type '{ email: string; }' is not assignable to parameter of type 'DefussRecord'"},{"fix":"Rename file to .mjs, or add `\"type\": \"module\"` to package.json.","cause":"Using import in a CommonJS (.js with no type:module) file.","error":"Cannot use import statement outside a module"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/kyr0/defuss#readme","github":"https://github.com/kyr0/defuss","docs":null,"changelog":null,"pypi":null,"npm":"defuss-db","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}