Package Exports

flintdb
flintdb/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (flintdb) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

FlintDB

The local database that should have existed. JSON-native, analytics built-in, vector search included.

npm install flintdb

Quick Start

import { open, col, avg } from "flintdb";

const db = await open("./data");

// Insert documents
await db.put("users", { name: "Alice", age: 30, role: "engineer" });
await db.put("users", { name: "Bob", age: 25, role: "designer" });
await db.put("users", { name: "Charlie", age: 35, role: "engineer" });

// Query with method chains
const result = await db
  .from("users")
  .where({ role: "engineer", age: { gte: 28 } })
  .sort("age")
  .run();

console.log(result.rows); // [Alice, Charlie]

db.close();

Features

No SQL -- query with plain objects and method chains
Two modes -- native in-process (napi-rs, ~~2us/read) or async IPC daemon (~~50us/read)
Analytics built-in -- aggregations, window functions, financial indicators, statistics
Vector search -- cosine/L2 nearest-neighbor, no extensions needed
TypeScript first -- full type definitions included
Zero config -- no server, no setup, just open() and go

Native vs IPC Mode

FlintDB ships with two execution modes:

Mode	API	Latency	Use case
Native	`FlintDB.open()`	~2us/read	Performance-critical, sync API
IPC (default)	`await open()`	~50us/read	Async, non-blocking

// IPC mode (async, default)
import { open } from "flintdb";
const db = await open("./data");

// Native mode (sync, in-process via napi-rs)
import { FlintDB } from "flintdb";
const db = FlintDB.open("./data");

CRUD

// Insert (auto-generated ID)
const id = await db.put("users", { name: "Alice", age: 30 });

// Insert with explicit ID
await db.put("users", { name: "Bob", age: 25 }, "bob-1");

// Get by ID
const doc = await db.get("users", id);
// { id, data: { name: "Alice", ... }, created_at, updated_at }

// Delete
await db.delete("users", id);

// Batch insert
await db.putBatch("users", [
  { name: "Alice", age: 30 },
  { name: "Bob", age: 25 },
  { name: "Charlie", age: 35 },
]);

Query Builder

The method-chain API is the recommended way to build queries:

import { col, avg, count } from "flintdb";

// Filter + sort + limit
const result = await db
  .from("users")
  .where({ role: "engineer" })
  .sort("age", true) // descending
  .limit(10)
  .run();

// Aggregation with groupBy
const stats = await db
  .from("trades")
  .select({
    symbol: col("symbol"),
    avgPrice: avg("price"),
    total: count("price"),
  })
  .groupBy("symbol")
  .sort("avgPrice", true)
  .run();

// Time-based filtering
const recent = await db
  .from("prices")
  .last(30, "days", "date")
  .sort("date")
  .run();

// Compound filters
const result = await db
  .from("users")
  .where({ age: { gte: 25 }, role: "engineer" })
  .run();

// Delete matching documents
const deleted = await db
  .from("logs")
  .where({ level: "debug" })
  .delete();

// Update matching documents
const updated = await db
  .from("users")
  .where({ role: "intern" })
  .update({ role: "junior" });

Filter Operators

Operator	Example	Description
equality	`{ role: "admin" }`	Equals
`ne`	`{ status: { ne: "deleted" } }`	Not equals
`gt`	`{ age: { gt: 18 } }`	Greater than
`gte`	`{ age: { gte: 18 } }`	Greater than or equal
`lt`	`{ price: { lt: 100 } }`	Less than
`lte`	`{ price: { lte: 100 } }`	Less than or equal
`in`	`{ status: { in: ["active", "pending"] } }`	In list

Multiple conditions in .where() are combined with AND.

Raw Queries

You can also pass query specs as plain objects:

const result = await db.query({
  from: "users",
  filter: { op: "gte", field: "age", value: 28 },
  sort: { field: "age", descending: false },
  limit: 10,
});

Indexes

// Hash index (fast equality lookups)
await db.createIndex("users", "email");

// BTree index (range queries, sorting)
await db.createIndex("users", "age", "btree");

// Drop an index
await db.dropIndex("users", "age");

Analytics

Built-in window functions and financial indicators -- no external libraries needed.

import { col, ema, stddev, pctChange, bollinger, rsi, macd } from "flintdb";

// Moving averages and statistics
const analysis = await db
  .from("prices")
  .select({
    date: col("date"),
    close: col("close"),
    ema20: ema("close", 20),
    volatility: stddev("close"),
    dailyReturn: pctChange("close"),
  })
  .window({ orderBy: "date", rows: 20 })
  .sort("date")
  .run();

// Financial indicators
const signals = await db
  .from("prices")
  .select({
    date: col("date"),
    rsi: rsi("close", 14),
    macd: macd("close"),
    bands: bollinger("close", 20, 2),
  })
  .window({ orderBy: "date", rows: 50 })
  .run();

Available Functions

Core: col, avg, min, max, sum, count, rank, stddev, pctChange, percentile, ema, bandwidth

Finance (Pro): macd, bollinger, rsi, ichimoku, vwap, seasonalDecompose, changePointDetect

Statistics (Pro): tTest, anovaTest, chiSquare, linearForecast, anomalyDetect, clusterKMeans

Vector Search

// Store documents with embeddings
await db.put("articles", {
  title: "Introduction to ML",
  embedding: [0.1, 0.2, 0.3, /* ... */],
});

// Direct search
const results = await db.nearVector("articles", "embedding", queryVector, {
  topK: 5,
  metric: "cosine",
});

// Builder pattern with pre-filtering
const results = await db
  .from("articles")
  .where({ category: "tech" })
  .nearVector("embedding", queryVector, { topK: 10, metric: "cosine" })
  .run();

for (const r of results) {
  console.log(r.score, r.data.title);
}

Views

Define virtual collections with JSONPath field mappings:

// Define a view
await db.defineView("user_summary", "users", {
  full_name: "$.name",
  years: "$.age",
});

// Query the view
const result = await db.queryView("user_summary", { limit: 10 });

// Builder pattern
const result = await db
  .view("user_summary")
  .where({ years: { gte: 30 } })
  .sort("years")
  .select("full_name", "years")
  .run();

// List / drop views
await db.listViews();
await db.dropView("user_summary");

Aliases

Map alternative field names to canonical ones:

await db.defineAlias("trades", "price", ["Price", "PRICE", "trade_price"]);
// Now queries on "Price" or "PRICE" resolve to "price"

await db.listAliases("trades");
await db.removeAlias("trades", "price");

Transactions

Atomic batch operations -- all succeed or all fail:

// Direct
await db.atomicBatch("accounts", [
  { op: "put", data: { name: "New Account", balance: 0 } },
  { op: "delete", id: "old-account-id" },
]);

// Builder pattern
await db.transaction("accounts", (tx) => {
  tx.put({ name: "Account A", balance: 1000 });
  tx.put({ name: "Account B", balance: 500 });
  tx.delete("old-id");
});

Buffered Writer

Auto-batching for high-throughput ingestion:

import { BufferedWriter } from "flintdb";

const writer = new BufferedWriter(db, "events", 1000); // batch size

for (const event of events) {
  await writer.put(event); // auto-flushes every 1000 docs
}
await writer.flush(); // flush remaining

console.log(`Wrote ${writer.written} documents`);

Collections & Schema

// List all collections
await db.listCollections(); // ["users", "trades"]

// Describe schema (inferred from data)
await db.describe("users");

// Get distinct values
await db.distinct("users", "role"); // ["engineer", "designer"]

Bulk Operations

// Delete matching documents
const deleted = await db.deleteMany("logs", {
  op: "lt", field: "timestamp", value: "2024-01-01",
});

// Update matching documents
const updated = await db.updateMany(
  "users",
  { op: "eq", field: "role", value: "intern" },
  { role: "junior" },
);

License

MIT