Documents & IDs

Everything stored in file-json-db is a plain JavaScript object (a “document”). There is no schema enforcement – you can put any JSON-serializable data you want.

What is a document?

A document is a normal object that can be converted to JSON:

{
  name: 'Ada Lovelace',
  email: 'ada@analytical.engine',
  age: 36,
  tags: ['math', 'computing'],
  address: {
    city: 'London',
    country: 'UK'
  },
  active: true,
  createdAt: '2026-01-15T10:00:00.000Z'
}

Nested objects, arrays, numbers, strings, booleans and null are all fine. Functions, Symbols, and circular references are not supported (JSON cannot represent them).

The primary key (ID)

Every document should have a unique identifier. By default the field is called _id, but you can change it with the idField option.

Automatic ID generation

When autoId: true is set, the library generates an ID if the document does not already have one:

const users = db.collection({
  name: 'users',
  autoId: true,
  idType: 'auto'     // sequential integers
});

const u = users.insert({ name: 'Alice' });
console.log(u._id);  // → 1

const u2 = users.insert({ name: 'Bob' });
console.log(u2._id); // → 2

ID types

Custom ID field name

const products = db.collection({
  name: 'products',
  autoId: true,
  idField: 'sku',      // use "sku" instead of "_id"
  idType: 'uuid'
});

const p = products.insert({ name: 'Widget', price: 9.99 });
console.log(p.sku);    // → a UUID string
console.log(p._id);    // → undefined

Providing your own ID

If you supply the ID field yourself, the library uses your value and does not overwrite it:

users.insert({
  _id: 'custom-001',
  name: 'Charlie'
});

Nested documents

Documents can contain nested objects and arrays. You can query them with dot notation:

users.insert({
  name: 'Dana',
  profile: {
    bio: 'Developer',
    social: {
      twitter: '@dana',
      github: 'dana-dev'
    }
  },
  scores: [10, 20, 30]
});

// Query nested field
users.findOne({ 'profile.social.github': 'dana-dev' });

What is stored on disk

Part files contain plain JSON arrays of documents. Example content of part-0001.json:

[
  {
    "_id": 1,
    "name": "Alice",
    "email": "alice@example.com",
    "age": 28
  },
  {
    "_id": 2,
    "name": "Bob",
    "email": "bob@example.com",
    "age": 32
  }
]