Registry / database / camadb

camadb

JSON →
library2.0.0jsnpmunverified

CamaDB is an embedded NoSQL database written in pure TypeScript, supporting Node.js, Electron, and browser environments. Its current stable version is 2.0.0 (January 2023), and it is under active development. CamaDB provides a MongoDB-style API for querying (SiftJS), updating (Obop), and aggregation (Mingo, with some limitations), offering full TypeScript support. It differentiates itself by providing frictionless integration across runtimes, handling native JavaScript data types, and aiming for fast performance on datasets up to 1 million rows, bypassing common issues with native database bindings in environments like Electron.

npm install camadb
INSTALL
IMPORT
SIG · CAMADB
C
camadb
databasejavascriptv2.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

Cama
import { Cama } from 'camadb';
const { Cama } = require('camadb');
CamaDB is primarily an ESM-first library. While CommonJS might work with transpilation, direct require() is not the recommended approach. TypeScript types are included.
CamaConfig
import type { CamaConfig } from 'camadb';
import { CamaConfig } from 'camadb';
When importing only a type, it's best practice in modern TypeScript to use 'import type' to ensure it's removed during compilation and avoids potential runtime issues.
Collection
const collection = await database.initCollection(...);
import { Collection } from 'camadb';
The `Collection` class is not directly exported for import. Instead, instances of `Collection` are created and returned by the `Cama` database instance's `initCollection` method.

Demonstrates initializing a CamaDB instance and a collection with a type interface, then inserting a document, and performing basic find and update operations.

import { Cama } from 'camadb'; // Ensure reflect-metadata is imported if decorators are used, often at the top level // import 'reflect-metadata'; interface User { _id: string; name: string; email: string; registrationDate: Date; preferences: { theme: string; notifications: boolean; }; } async function setupCamaDB() { // Initialize the database instance with filesystem persistence const database = new Cama({ path: './.cama-data', persistenceAdapter: 'fs', // Use 'indexeddb' or 'localstorage' for browser environments logLevel: 'info' // Can be 'debug' for more verbose logging }); // Initialize a collection named 'users' with a specific date column for proper type handling const usersCollection = await database.initCollection<User>('users', { columns: [{ type: 'date', title: 'registrationDate' // Essential for CamaDB to correctly store and retrieve Date objects }], indexes: [], // Indexes are not yet implemented but are part of the configuration API }); // Insert a new user document into the collection const newUser: User = { _id: 'user_001', name: 'Alice Wonderland', email: 'alice@example.com', registrationDate: new Date(), preferences: { theme: 'dark', notifications: true } }; await usersCollection.insertOne(newUser); console.log('User inserted successfully:', newUser._id); // Example of finding a user by _id const foundUser = await usersCollection.findMany({ _id: 'user_001' }); console.log('Found user:', foundUser); // Example of updating a user's preferences await usersCollection.updateMany({ _id: 'user_001' }, { $set: { 'preferences.theme': 'light' } }); console.log('User preferences updated.'); } setupCamaDB().catch(console.error);
Debug
Known issues
breakingVersion 2.0.0 introduced a breaking change by centralizing the internal queuing system. This may affect applications that interacted directly with previous internal queue mechanisms or custom persistence adapters.
fix
Review any custom logic interacting with CamaDB's internal operation queues or persistence layer if upgrading from versions prior to 2.0.0. Ensure compatibility with the new centralized system.
affects: >=2.0.0
gotchaIndexes are not yet implemented, which may impact query performance on very large datasets, especially without highly selective filters. The library states it is fast even without them, but complex queries might suffer.
fix
Optimize queries by using precise filters to reduce the dataset size that needs to be scanned. For critical performance, consider implementing application-level caching or pre-processing data.
affects: >=1.0.0
gotchaRich text search functionality is currently missing. For full-text search capabilities, an external library or custom implementation is required.
fix
Integrate a third-party full-text search library (e.g., FlexSearch, Lunr.js) or develop a custom keyword-matching solution for your data.
affects: >=1.0.0
gotchaThe Mingo-powered aggregation engine in CamaDB does not support all MongoDB aggregation commands, specifically 'lookup' commands are not available.
fix
Refactor complex aggregation queries that would typically use '$lookup' into multiple `find` operations, then join and process the results within your application code.
affects: >=1.0.0
gotchaCamaDB uses `reflect-metadata` for type reflection. If not configured correctly (e.g., missing import, `tsconfig.json` settings), this can lead to runtime errors, particularly with features relying on decorator metadata.
fix
Ensure `import "reflect-metadata";` is present at the very top of your application's entry file. Additionally, `emitDecoratorMetadata` and `experimentalDecorators` must be set to `true` in your `tsconfig.json`.
affects: >=1.0.0
Errors
Common errors & fixes
ReferenceError: Reflect is not defined
The `reflect-metadata` polyfill was not imported or configured correctly, which CamaDB relies on for TypeScript type reflection.
fix
Add `import "reflect-metadata";` at the top of your main application entry file. Also, ensure `emitDecoratorMetadata` and `experimentalDecorators` are `true` in your `tsconfig.json`.
Error: Persistence adapter 'fs' requires a Node.js environment.
Attempting to use a persistence adapter (e.g., 'fs') in an unsupported JavaScript runtime (e.g., browser), or conversely, trying to use a browser-specific adapter in Node.js.
fix
Configure the `persistenceAdapter` option during `Cama` initialization to match your target environment: use `'fs'` for Node.js/Electron, and `'indexeddb'` or `'localstorage'` for browser-based applications.
TypeError: Cannot read properties of undefined (reading 'toISOString')
Inserting or retrieving a `Date` object into a collection column that was not explicitly defined with `type: 'date'` in the `initCollection` options, leading to incorrect serialization/deserialization.
fix
When initializing a collection via `database.initCollection`, ensure that any columns intended to store `Date` objects have `type: 'date'` specified in their column definition, e.g., `{ type: 'date', title: 'myDateColumn' }`.
Error: Collection 'myCollectionName' already exists.
Attempting to call `database.initCollection()` for a collection that has already been initialized on the current database instance, which is not permitted.
fix
Ensure `database.initCollection()` is called only once per collection name per database instance. Store the returned `Collection` instance and reuse it throughout your application.
Upgrade
Version history
2.0.0latest on npm
Audit
Dependencies
reflect-metadatarequiredRequired for decorator-based type reflection, especially for column type definition and proper type inference at runtime. Must be imported once, typically at the application entry point.
Agent activity
17 hits · last 30 days
node
14
Amazon
1
OpenAI (training)
1
Resources