Core

Documents

A document is a plain JavaScript object. SinterDB stores it in a compact binary form and returns it as an object again, with the same value types.

Supported values

Anything else is rejected before it is sent, with a SinterDocumentError. That includes undefined, functions, symbols, and class instances such as Map and Set.

The _id field

Every document has an _id, and it is always a CustomId. If you insert a document without one, the server generates it.

import { CustomId } from "sinterdb";

const { insertedId } = await users.insertOne({ name: "Kage" });
insertedId.toHexString(); // "6710f3c2..."
insertedId.timestamp; // when it was generated

const id = CustomId.generate();
await users.insertOne({ _id: id, name: "Rin" });

const same = CustomId.fromHexString(id.toHexString());
same.equals(id); // true

• Plain strings and numbers are not accepted as _id.
• _id cannot be changed after insert.
• Compare ids with equals(), not ===, since two CustomId objects with the same value are different objects.

In TypeScript, OptionalId is the shape you insert (with _id optional) and WithId is the shape you read back (with _id always present).

How values are compared

Values are compared by their stored form, so a few pairs that look alike are different:

• 1 and 1n are different values, because a number and a bigint are stored differently.
• 0 and -0 are different under equality, but equal in ranges and sorting. Avoid storing -0.
• A field set to null is not the same as a missing field.

The Filters page covers what this means for queries.

Field order

Fields come back sorted by name, not in the order you wrote them:

await users.insertOne({ name: "Kage", age: 30 });
await users.findOne({ name: "Kage" });
// { _id: ..., age: 30, name: "Kage" }

Arrays keep their order. Don't depend on the order of an object's keys.

Limits

Keep documents far below 16 MiB. A query result is split into batches automatically, but a single document has to fit in one message.