Follicle

3.1.0 verified Fri May 01 auth: no javascript

Follicle is a class-based ES6 ODM (Object Document Mapper) for MongoDB and NeDB, forked from camo to support multiple concurrent database connections. Current version is 3.1.0 (stable, requires Node >=12). It provides a familiar OOP interface with ES6 classes, native Promises, and support for embedded documents, hooks, and counting. Unlike Mongoose, it offers a lighter-weight approach and supports NeDB as an alternative backend for development or in-memory usage. Release cadence is irregular; maintained by Seald.

Common errors

error Error: Cannot find module 'follicle' ↓

cause Follicle is not installed or not resolved due to ESM configuration.

fix

Run 'npm install follicle --save' and ensure 'type': 'module' in package.json if using ESM.

error TypeError: connect is not a function ↓

cause Using require() on an ESM-only export.

fix

Replace require() with import { connect } from 'follicle'.

error Error: No database backend found. Please install @seald-io/nedb or mongodb. ↓

cause Missing backend dependency.

fix

Install npm install @seald-io/nedb (for development) or npm install mongodb (for production).

Warnings

gotcha The package is ESM-only since v3.0.0. Importing with require() will fail. ↓

fix Use import statements and set type: 'module' in package.json, or use dynamic import().

gotcha You must install at least one backend driver (@seald-io/nedb or mongodb) or require it at runtime. Follicle will throw if no backend is available. ↓

fix Run 'npm install @seald-io/nedb' for development or 'npm install mongodb' for production.

deprecated Using `connect()` with NeDB may have connection pool limitations compared to MongoDB; NeDB support is considered legacy. ↓

fix Migrate to MongoDB for production workloads.

Install

npm install follicle

yarn add follicle

pnpm add follicle

Imports

connect

wrong

const connect = require('follicle').connect

correct

import { connect } from 'follicle'

ESM-only; CommonJS require is not supported for named exports.

Document

wrong

const { Document } = require('follicle')

correct

import { Document } from 'follicle'

ESM-only; Document is a named export.

EmbeddedDocument
```
import { EmbeddedDocument } from 'follicle'
```
Named export for defining embedded schemas.

Quickstart

Shows connecting to MongoDB, defining a document class, creating and saving a document, and querying with a filter.

import { connect, Document } from 'follicle';

(async () => {
  const database = await connect('mongodb://localhost:27017/mydb');

  class User extends Document {
    constructor() {
      super();
      this.name = '';
      this.email = '';
      this.age = 0;
    }
  }

  const user = User.create({
    name: 'Jane Doe',
    email: 'jane@example.com',
    age: 30
  });
  await user.save();

  const users = await User.find({ age: { $gte: 18 } });
  console.log(users);

  await database.close();
})().catch(console.error);