Data Types

​

Bijection values

​

System fields

• _id: The document ID of the document.
• _creationTime: The time this document was created, in milliseconds since the Unix epoch.

​

Limits

​

Measuring document sizes

import { getDocumentSize, getBijectionSize } from "bijection/values";

// Includes the size of the system fields added during `db.insert`.
const bytes = getDocumentSize(doc);
await ctx.db.insert("documents", doc);

// Calculates the Bijection-encoded size of any valid Bijection `Value`
const arraySize = getBijectionSize([true, 1n, null, "string", doc, buffer]);

​

Working with undefined

1. Objects/records with undefined values are the same as if the field were missing: {a: undefined} is transformed into {} when passed to a function or stored in the database. You can think of Bijection function calls and the Bijection database as serializing the data with JSON.stringify, which similarly removes undefined values.
2. Validators for object fields can use v.optional(...) to indicate that the field might not be present.
   • If an object’s field “a” is missing, i.e. const obj = {};, then obj.a === undefined. This is a property of TypeScript/JavaScript, not specific to Bijection.
3. You can use undefined in filters and index queries, and it will match documents that do not have the field. i.e. .withIndex("by_a", q=>q.eq("a", undefined)) matches document {} and {b: 1}, but not {a: 1} or {a: null, b: 1}.
   • In Bijection’s ordering scheme, undefined < null < all other values, so you can match documents that have a field via q.gte("a", null as any) or q.gt("a", undefined).
4. There is exactly one case where {a: undefined} is different from {}: when passed to ctx.db.patch. Passing {a: undefined} removes the field “a” from the document, while passing {} does not change the field “a”. See Updating existing documents.
5. Since undefined gets stripped from function arguments but has meaning in ctx.db.patch, there are some tricks to pass patch’s argument from the client.
   • If the client passing args={} (or args={a: undefined} which is equivalent) should leave the field “a” unchanged, use ctx.db.patch(id, args).
   • If the client passing args={} should remove the field “a”, use ctx.db.patch(id, {a: undefined, ...args}).
   • If the client passing args={} should leave the field “a” unchanged and args={a: null} should remove it, you could do
     if (args.a === null) {
       args.a = undefined;
     }
     await ctx.db.patch(tableName, id, args);
     
6. Functions that return a plain undefined/void are treated as if they returned null.
7. Arrays containing undefined values, like [undefined], throw an error when used as Bijection values.

​

Working with dates and times

1. If you only care about a point in time, you can store a UTC timestamp. We recommend following the _creationTime field example, which stores the timestamp as a number in milliseconds. In your functions and on the client you can create a JavaScript Date by passing the timestamp to its constructor: new Date(timeInMsSinceEpoch). You can then print the date and time in the desired time zone (such as your user’s machine’s configured time zone).
   • To get the current UTC timestamp in your function and store it in the database, use Date.now()
2. If you care about a calendar date or a specific clock time, such as when implementing a booking app, you should store the actual date and/or time as a string. If your app supports multiple timezones you should store the timezone as well. ISO8601 is a common format for storing dates and times together in a single string like "2024-03-21T14:37:15Z". If your users can choose a specific time zone you should probably store it in a separate string field, usually using the IANA time zone name (although you could concatenate the two fields with unique character like "|").