fastdb4ts

Browser-oriented TypeScript bindings for fastdb, powered by WebAssembly.

fastdb4ts brings the fastdb storage model to TypeScript with a browser-first API centered around typed schemas, structured table access, and binary buffer transport.

What this package provides

• Typed schemas
  • model records with Feature subclasses and defineSchema(...)
• Structured table access
  • use ORM, TableDefn, Table, and column accessors
• Binary buffer roundtrips
  • import/export databases as Uint8Array / ArrayBuffer
• Legacy graph serialization
  • FastSerializer remains available for existing nested-feature and cyclic-reference users, but new cross-runtime provider work should use neutral schema descriptors and explicit codec profiles
• Shared native semantics
  • backed by the same C++ core as fastdb4py

Current scope

This package currently targets the browser/WebAssembly use case.

Included:

• browser-first WASM runtime
• Feature + defineSchema(...)
• ORM, TableDefn, Table, column access
• FastSerializer legacy compatibility APIs
• Uint8Array / ArrayBuffer import/export

Not included in the current TS package:

• shared-memory IPC
• direct filesystem persistence APIs

Installation

npm install fastdb4ts

If you are working from the repository source instead of npm:

bash ts/build-wasm.sh
npm --prefix ts/fastdb4ts run build

Quick start

import {
  F64,
  Feature,
  ORM,
  TableDefn,
  defineSchema,
  initFastdb,
} from 'fastdb4ts';

await initFastdb();

class Point extends Feature {
  static schema = defineSchema({
    x: F64,
    y: F64,
  });
}

const db = ORM.truncate([new TableDefn(Point, 3)]);
const table = db.table(Point);

table.column.x.fill([1.5, 2.5, 3.5]);
table.column.y.fill([4.5, 5.5, 6.5]);

console.log(table.get(1).x); // 2.5

Defining schemas

Unlike fastdb4py, the TypeScript package uses explicit schema definitions rather than Python annotations.

You can write these schemas by hand, or auto-generate them from Python Feature classes using the fdb codegen CLI (see Generating schemas from Python below).

import {
  F64,
  Feature,
  I32,
  STR,
  defineSchema,
  listOf,
  ref,
} from 'fastdb4ts';

class Point extends Feature {
  static schema = defineSchema({
    x: F64,
    y: F64,
  });
}

class Line extends Feature {
  static schema = defineSchema({
    id: I32,
    name: STR,
    points: listOf(Point),
    first: ref(Point),
  });
}

Common field helpers:

• U8, U16, U32, I32
• F32, F64
• STR, WSTR
• BYTES
• ref(TargetFeature)
• listOf(...)

Working with tables

Fixed-size tables

import { F64, Feature, ORM, TableDefn, defineSchema, initFastdb } from 'fastdb4ts';

await initFastdb();

class Particle extends Feature {
  static schema = defineSchema({
    x: F64,
    y: F64,
    vx: F64,
    vy: F64,
  });
}

const db = ORM.truncate([new TableDefn(Particle, 4)]);
const table = db.table(Particle);

table.column.x.fill([0.0, 1.0, 2.0, 3.0]);
table.column.y.fill([10.0, 20.0, 30.0, 40.0]);
table.column.vx.fill([0.1, 0.1, 0.2, 0.2]);
table.column.vy.fill([0.0, 0.0, 0.0, 0.0]);

console.log(table.get(2).x); // 2.0

Buffer roundtrip

const bytes = db.toBuffer();
const copy = ORM.fromBuffer(bytes);
const copyTable = copy.table(Particle);

console.log(copyTable.get(2).x); // 2.0

FastSerializer Legacy Compatibility

FastSerializer is the legacy graph-oriented layer for feature graphs that are more naturally represented as nested objects than flat tables. It remains available for compatibility and migration tests, but it is not the foundation for new C-Two provider work.

Supported scenarios include:

• nested features
• scalar lists
• string lists
• feature references
• cyclic references
• numeric-list columnar auxiliary layers

import {
  F64,
  FastSerializer,
  Feature,
  I32,
  defineSchema,
  initFastdb,
  listOf,
} from 'fastdb4ts';

await initFastdb();

class Point extends Feature {
  static schema = defineSchema({ x: F64, y: F64 });
}

class Line extends Feature {
  static schema = defineSchema({
    id: I32,
    points: listOf(Point),
  });
}

const line = new Line({
  id: 42,
  points: [new Point({ x: 1.0, y: 2.0 }), new Point({ x: 3.0, y: 4.0 })],
});

const bytes = FastSerializer.dumps(line);
const copy = FastSerializer.loads(bytes, Line);

console.log(copy.points[1].y); // 4.0

Cycles are preserved:

import { Feature, I32, FastSerializer, defineSchema, initFastdb, ref } from 'fastdb4ts';

await initFastdb();

class Node extends Feature {
  static schema = defineSchema({
    val: I32,
    next: ref(() => Node),
  });
}

const a = new Node({ val: 1 });
const b = new Node({ val: 2 });
a.next = b;
b.next = a;

const copy = FastSerializer.loads(FastSerializer.dumps(a), Node);
console.log(copy.next.next === copy); // true

Build

From the repository root:

npm --prefix ts/fastdb4ts run build

To rebuild the WASM module as well:

bash ts/build-wasm.sh
npm --prefix ts/fastdb4ts run build

Tests

Pure TypeScript tests live under tests/ts/.

Run them from the repository root:

npm run test:ts

Serializer interop validation is also available:

npm --prefix ts/fastdb4ts run test:serializer:interop

Generating schemas from Python

If you define your canonical Feature classes in Python (fastdb4py), you can generate the equivalent TypeScript schemas automatically using the fdb codegen CLI:

pip install fastdb4py
fdb codegen --ts ./python_features/ ./ts_features/

This generates one .ts file per .py file, with:

• all field types mapped (F64, STR, ref(...), listOf(...), etc.)
• cross-file imports resolved to relative paths
• circular references using lazy refs ref(() => ClassName)
• topological class ordering within each file

See the Python binding README for full codegen documentation.

Repository documentation

For fuller project documentation, see:

• repository overview: README.md
• TypeScript/WASM binding guide: ts/README.md
• C++ core guide: fastcarto/README.md
• Python binding guide: python/README.md