API Reference

Complete reference for the public surface of file-json-db v1.5.0. Types are shown in TypeScript style for clarity.

JSONDB

new JSONDB(dbPath?: string) → JSONDB

Create or open a database at the given path (default ./database).

Methods

Method	Returns	Description
`collection(nameOrOptions)`	`Collection`	Get or create a collection
`createCollection(nameOrOptions)`	`Collection`	Alias of `collection`
`listCollections()`	`string[]`	Names of collections found on disk
`dropCollection(name)`	`boolean`	Delete collection directory
`unloadCollection(name)`	`boolean`	Remove collection from memory
`backup(backupRoot?, options?)`	`string \| null`	Snapshot all collections
`backupAsync(backupRoot?, options?)`	`Promise<string \| null>`	Async backup

CollectionOptions

interface CollectionOptions {
  name: string;
  autoId?: boolean;          // default false
  idField?: string;          // default '_id'
  idType?: 'auto' | 'uuid' | 'objectid';  // default 'auto'
  indexes?: string[];        // default []
  pretty?: boolean;          // default true
  maxPartSize?: number;      // default 256 * 1024
  maxRecords?: number | null;
  errorLevel?: 'debug' | 'ignore';  // default 'debug'
  keepIdIndex?: boolean;     // default false – compact ranges for auto IDs
}

Collection

Insert

insert(doc: object) → object | null

insertAsync(doc: object) → Promise<object | null>

insertMany(docs: object[]) → object[]

insertManyAsync(docs: object[]) → Promise<object[]>

Find

find(query?: object) → QueryBuilder

findAsync(query?: object) → Promise<QueryBuilder>

findOne(query?: object) → object | null

findOneAsync(query?: object) → Promise<object | null>

Search (new in 1.5.0)

search(options: SearchOptions) → QueryBuilder

searchAsync(options: SearchOptions) → Promise<QueryBuilder>

interface SearchOptions {
  keyword: string;                 // required
  fields?: string[] | null;        // null = all fields
  exclude?: string[];              // fields to skip
  caseInsensitive?: boolean;       // default true
}

Simple keyword (contains) search. Returns a QueryBuilder so you can still chain .limit(), .sort(), .project(), .toArray(), etc. See the Search API page for full details and examples.

Update

updateOne(filter: object, update: object) → object | null

updateOneAsync(filter, update) → Promise<object | null>

updateMany(filter, update) → object[]

updateManyAsync(filter, update) → Promise<object[]>

updateFunc(filter, fn, options?) → object | object[] | null

updateFuncAsync(filter, fn, options?) → Promise<…>

Delete

deleteOne(filter: object) → object | null

deleteOneAsync(filter) → Promise<object | null>

deleteMany(filter) → object[]

deleteManyAsync(filter) → Promise<object[]>

Other

startTransaction() → Transaction

aggregate(pipeline?: object[]) → object[]

import(filePath: string, options?: ImportOptions) → boolean

importAsync(filePath, options?) → Promise<boolean>

rebuildIndexes() → void

rebuildId() → number

QueryBuilder

limit(n: number) → this

skip(n: number) → this

sort(spec: object) → this

project(spec: object) → this

Supports inclusion ({name:1}), exclusion ({password:0}), mixed (exclusion wins), and _id is kept by default (use _id:0 to hide). Improved in 1.5.0.

toArray() → object[]

first() → object | null

count() → number

Transaction

Same mutation methods as Collection (insert, updateOne, deleteMany, … plus their Async variants), plus:

commit() → Promise<boolean>

rollback() → Promise<boolean>

Query operators (summary)

$eq $ne $gt $gte $lt $lte $in $nin $exists $regex $type $size $elemMatch $and $or $nor

See the Queries & Operators page for full explanations.

Update operators (summary)

$set $inc $push $pull $unset

See the Update Operators page for details.