CamaDB: TypeScript Embedded NoSQL Database

Common errors

• ReferenceError: Reflect is not defined

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

  cause 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')

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

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

Warnings

• breaking Version 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.
• gotcha Indexes 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.
• gotcha Rich 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.
• gotcha The 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.
• gotcha CamaDB 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`.

Install

• npm install camadb npm
• yarn add camadb yarn
• pnpm add camadb pnpm

Imports

• Cama
  wrong:

  const { Cama } = require('camadb');

  correct:

  import { Cama } from '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
  wrong:

  import { CamaConfig } from 'camadb';

  correct:

  import type { 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
  wrong:

  import { Collection } from 'camadb';

  correct:

  const collection = await database.initCollection(...);

  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.

Quickstart

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);