Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nickruigrok/baseflare/llms.txt

Use this file to discover all available pages before exploring further.

Baseflare uses plain UUIDv7 strings as document IDs. UUIDv7 is a time-sortable UUID format — the most significant 48 bits encode a Unix millisecond timestamp, which means ordering documents by _id is equivalent to ordering them by creation time. Because the timestamp is encoded directly in the ID, Baseflare derives the _createdAt field on every document from the ID at read time; no separate timestamp column is stored in the database. All ID utilities are exported from baseflare/values and can be used in both server-side handlers and client-side code.

​
Import

import {
  generateId,
  getCreatedAtFromId,
  getCreatedMsFromId,
  isUuidV7,
  minIdForMs,
  maxIdForMs,
} from 'baseflare/values'

​
generateId()

Generates a new UUIDv7 string using the current system time as the timestamp component. Each call produces a unique, time-ordered ID suitable for use as a document _id. Signature: 
generateId(): string
Returns: A new UUIDv7 string. 
import { generateId } from 'baseflare/values'

const id = generateId()
// → '019078e5-d29f-7b00-8000-1a2b3c4d5e6f'

// IDs generated in sequence are lexicographically sortable by creation time:
const id1 = generateId()
const id2 = generateId()
id1 < id2 // → true (id1 was created before id2)
You rarely need to call generateId() directly in application code — Baseflare automatically assigns a UUIDv7 _id when you insert a document via ctx.db.insert(). Use generateId() when you need to know the ID before performing the insert, for example to create cross-references between two documents in a single mutation.

​
getCreatedAtFromId(id)

Extracts the creation timestamp encoded in a UUIDv7 string and returns it as a JavaScript Date object. The timestamp has millisecond precision. Signature: 
getCreatedAtFromId(id: string): Date
​
id
string
required
A valid UUIDv7 string. Throws an Error if the string is not a valid UUIDv7.
Returns: A Date representing the millisecond the ID was created. 
import { getCreatedAtFromId } from 'baseflare/values'

const createdAt = getCreatedAtFromId('019078e5-d29f-7b00-8000-1a2b3c4d5e6f')
// → Date object representing the millisecond the ID was created

console.log(createdAt.toISOString())
// → '2024-01-15T10:30:00.000Z'

​
getCreatedMsFromId(id)

Extracts the creation timestamp encoded in a UUIDv7 string and returns it as milliseconds since the Unix epoch. Use this when you need a numeric timestamp rather than a Date object. Signature: 
getCreatedMsFromId(id: string): number
​
id
string
required
A valid UUIDv7 string. Throws an Error if the string is not a valid UUIDv7.
Returns: Milliseconds since Unix epoch (number). 
import { getCreatedMsFromId } from 'baseflare/values'

const ms = getCreatedMsFromId('019078e5-d29f-7b00-8000-1a2b3c4d5e6f')
// → 1705315800000

// Equivalent to:
new Date(ms).toISOString() // → '2024-01-15T10:30:00.000Z'

​
isUuidV7(value)

Tests whether a string is a well-formed UUIDv7. The check is purely structural (regex pattern match) — it does not validate that the timestamp is sensible or that the ID was generated by Baseflare. Signature: 
isUuidV7(value: string): boolean
​
value
string
required
The string to test.
Returns: true if value matches the UUIDv7 pattern, false otherwise. 
import { isUuidV7 } from 'baseflare/values'

isUuidV7('019078e5-d29f-7b00-8000-1a2b3c4d5e6f') // → true
isUuidV7('not-a-uuid')                             // → false
isUuidV7('550e8400-e29b-41d4-a716-446655440000')   // → false (UUIDv4, not v7)

​
minIdForMs(ms) and maxIdForMs(ms)

These two utilities produce the lexicographic minimum and maximum UUIDv7 strings for a given millisecond timestamp. They are primarily used internally to construct efficient time-range queries against _id — since IDs are time-ordered, a range query _id >= minIdForMs(start) AND _id <= maxIdForMs(end) scans only documents created in that time window. Signatures: 
minIdForMs(milliseconds: number): string
maxIdForMs(milliseconds: number): string
​
milliseconds
number
required
A Unix timestamp in milliseconds. Must be a safe integer between 0 and 281474976710655 (0xFFFFFFFFFFFF). Throws a ValidationError if out of range.
Returns: A UUIDv7 string that is the minimum or maximum possible ID for that millisecond. 
import { minIdForMs, maxIdForMs } from 'baseflare/values'

const start = new Date('2024-01-01T00:00:00Z').getTime()
const end   = new Date('2024-01-31T23:59:59.999Z').getTime()

const lower = minIdForMs(start)
const upper = maxIdForMs(end)

// Use in a custom DB range scan:
// WHERE _id >= lower AND _id <= upper

​
Id<TableName> Type

Id<TableName> is a branded string type that carries the table name as a compile-time phantom type parameter. At runtime it is just a plain string, but TypeScript will refuse to accept an Id<'users'> where an Id<'todos'> is expected. 
import type { Id } from 'baseflare/values'

// Explicitly typed ID variables:
const todoId: Id<'todos'> = '019078e5-d29f-7b00-8000-1a2b3c4d5e6f'

// TypeScript prevents mixing IDs from different tables:
function deleteTodo(id: Id<'todos'>) { /* ... */ }

const userId: Id<'users'> = generateId() as Id<'users'>
deleteTodo(userId) // ❌ TypeScript error: Id<'users'> is not assignable to Id<'todos'>
deleteTodo(todoId) // ✅
Using v.id('tableName') in a validator both validates the UUIDv7 format at runtime and provides the branded Id<'tableName'> TypeScript type for the field. You get full safety at both the runtime and type-system layers with a single declaration.

Build docs developers (and LLMs) love

Get started for freeTalk to us