Types

Core types

Document

Base interface for all documents stored in the database.

export interface Document {
  _id: string;
  [key: string]: unknown;
}

_id

string

required

Unique identifier for the document (auto-generated on insert)

[key: string]

unknown

Additional fields with any values

Example

import { Document } from '@sohzm/jasonisnthappy';

interface User extends Document {
  _id: string;
  name: string;
  email: string;
  age: number;
  tags: string[];
}

Configuration types

DatabaseOptions

Configuration options for opening a database.

export interface DatabaseOptions {
  cacheSize?: number;
  autoCheckpointThreshold?: number;
  filePermissions?: number;
  readOnly?: boolean;
  maxBulkOperations?: number;
  maxDocumentSize?: number;
  maxRequestBodySize?: number;
}

cacheSize

number

Size of the page cache in bytes. Larger cache improves read performance.

autoCheckpointThreshold

number

Number of pages written before automatic checkpoint triggers.

filePermissions

number

Unix file permissions for the database file (e.g., 0o644).

readOnly

boolean

Open database in read-only mode if true.

maxBulkOperations

number

Maximum number of operations allowed in a single bulk write.

maxDocumentSize

number

Maximum size of a single document in bytes.

maxRequestBodySize

number

Maximum request body size for web server (if enabled).

Example

const options: DatabaseOptions = {
  cacheSize: 1024 * 1024 * 100, // 100MB
  autoCheckpointThreshold: 1000,
  readOnly: false,
  maxBulkOperations: 10000,
  maxDocumentSize: 1024 * 1024 * 10 // 10MB
};

const db = Database.openWithOptions('./data.db', options);

TransactionConfig

Configuration for transaction retry behavior.

export interface TransactionConfig {
  maxRetries?: number;
  retryBackoffBaseMs?: number;
  maxRetryBackoffMs?: number;
}

maxRetries

number

Maximum number of retry attempts for conflicted transactions.

retryBackoffBaseMs

number

Base delay in milliseconds for exponential backoff.

maxRetryBackoffMs

number

Maximum delay in milliseconds between retries.

Example

const config: TransactionConfig = {
  maxRetries: 5,
  retryBackoffBaseMs: 10,
  maxRetryBackoffMs: 1000
};

db.setTransactionConfig(config);

Result types

UpsertResult

Result of an upsert operation.

export interface UpsertResult {
  id: string;
  inserted: boolean;
}

string

The document ID

inserted

boolean

true if document was inserted, false if it was updated

BulkWriteResult

Result of a bulk write operation.

export interface BulkWriteResult {
  inserted_count: number;
  updated_count: number;
  deleted_count: number;
  inserted_ids: string[];
  errors: BulkWriteError[];
}

inserted_count

number

Number of documents inserted

updated_count

number

Number of documents updated

deleted_count

number

Number of documents deleted

inserted_ids

string[]

Array of IDs for inserted documents

errors

BulkWriteError[]

Array of errors encountered

BulkWriteError

Error information from bulk write operations.

export interface BulkWriteError {
  operation_index: number;
  message: string;
}

operation_index

number

Index of the operation that failed

message

string

Error message

SearchResult

Result from full-text search operations.

export interface SearchResult {
  doc_id: string;
  score: number;
}

doc_id

string

Document ID of the matching document

score

number

Relevance score (higher is more relevant)

GarbageCollectResult

Result of garbage collection operation.

export interface GarbageCollectResult {
  pages_freed: number;
  bytes_freed: number;
}

pages_freed

number

Number of pages reclaimed

bytes_freed

number

Bytes of storage reclaimed

Information types

DatabaseInfo

Comprehensive database information.

export interface DatabaseInfo {
  path: string;
  version: number;
  num_pages: number;
  file_size: number;
  collections: CollectionInfo[];
  total_documents: number;
  read_only: boolean;
}

path

string

Database file path

version

number

Database schema version

num_pages

number

Total number of pages in the database

file_size

number

Database file size in bytes

collections

CollectionInfo[]

Array of collection information

total_documents

number

Total number of documents across all collections

read_only

boolean

Whether database is in read-only mode

CollectionInfo

Information about a collection.

export interface CollectionInfo {
  name: string;
  document_count: number;
  btree_root: number;
  indexes: IndexInfo[];
}

name

string

Collection name

document_count

number

Number of documents in the collection

btree_root

number

Root page number of the B-tree index

indexes

IndexInfo[]

Array of index information

IndexInfo

Information about an index.

export interface IndexInfo {
  name: string;
  fields: string[];
  unique: boolean;
  index_type: 'btree' | 'text';
}

name

string

Index name

fields

string[]

Array of field names in the index

unique

boolean

Whether the index enforces uniqueness

index_type

'btree' | 'text'

Type of index: 'btree' for B-tree index, 'text' for full-text search

BackupInfo

Information about a backup file.

export interface BackupInfo {
  path: string;
  version: number;
  collections: string[];
  total_documents: number;
}

path

string

Backup file path

version

number

Database version

collections

string[]

Array of collection names in the backup

total_documents

number

Total number of documents in the backup

MetricsSnapshot

Database operation metrics.

export interface MetricsSnapshot {
  documents_written: number;
  documents_read: number;
  total_document_operations: number;
  io_errors: number;
  transaction_conflicts: number;
}

documents_written

number

Total number of document write operations

documents_read

number

Total number of document read operations

total_document_operations

number

Total number of all document operations

io_errors

number

Number of I/O errors encountered

transaction_conflicts

number

Number of transaction conflicts

Operation types

BulkOperation

Union type for bulk write operations.

export type BulkOperation<T = Record<string, unknown>> =
  | BulkInsertOp<T>
  | BulkUpdateOneOp
  | BulkUpdateManyOp
  | BulkDeleteOneOp
  | BulkDeleteManyOp;

BulkInsertOp

Bulk insert operation.

export interface BulkInsertOp<T> {
  op: 'insert';
  doc: T;
}

'insert'

required

Operation type

doc

required

Document to insert

BulkUpdateOneOp

Bulk update single document operation.

export interface BulkUpdateOneOp {
  op: 'update_one';
  filter: string;
  update: Record<string, unknown>;
}

'update_one'

required

Operation type

filter

string

required

JMESPath filter to match document

update

Record<string, unknown>

required

Fields to update

BulkUpdateManyOp

Bulk update multiple documents operation.

export interface BulkUpdateManyOp {
  op: 'update_many';
  filter: string;
  update: Record<string, unknown>;
}

'update_many'

required

Operation type

filter

string

required

JMESPath filter to match documents

update

Record<string, unknown>

required

Fields to update

BulkDeleteOneOp

Bulk delete single document operation.

export interface BulkDeleteOneOp {
  op: 'delete_one';
  filter: string;
}

'delete_one'

required

Operation type

filter

string

required

JMESPath filter to match document

BulkDeleteManyOp

Bulk delete multiple documents operation.

export interface BulkDeleteManyOp {
  op: 'delete_many';
  filter: string;
}

'delete_many'

required

Operation type

filter

string

required

JMESPath filter to match documents

Example

import { BulkOperation } from '@sohzm/jasonisnthappy';

const operations: BulkOperation<Omit<User, '_id'>>[] = [
  {
    op: 'insert',
    doc: { name: 'Alice', email: '[email protected]', age: 30 }
  },
  {
    op: 'update_one',
    filter: '[?email == `[email protected]`]',
    update: { age: 26 }
  },
  {
    op: 'update_many',
    filter: '[?age < `18`]',
    update: { status: 'minor' }
  },
  {
    op: 'delete_one',
    filter: '[?email == `[email protected]`]'
  },
  {
    op: 'delete_many',
    filter: '[?active == `false`]'
  }
];

const result = users.bulkWrite(operations);

Aggregation types

AggregationStage

Aggregation pipeline stage.

export interface AggregationStage {
  match?: string;
  group_by?: string;
  count?: string;
  sum?: { field: string; output: string };
  avg?: { field: string; output: string };
  min?: { field: string; output: string };
  max?: { field: string; output: string };
  sort?: { field: string; asc?: boolean };
  limit?: number;
  skip?: number;
  project?: string[];
  exclude?: string[];
}

match

string

JMESPath filter to match documents

group_by

string

Field name to group by

count

string

Output field name for count

sum

{ field: string; output: string }

Sum aggregation: field to sum, output field name for result

avg

{ field: string; output: string }

Average aggregation: field to average, output field name for result

min

{ field: string; output: string }

Minimum aggregation: field to find min, output field name for result

max

{ field: string; output: string }

Maximum aggregation: field to find max, output field name for result

sort

{ field: string; asc?: boolean }

Sort by field: field to sort by, asc for ascending (default: true)

limit

number

Maximum number of documents to return

skip

number

Number of documents to skip

project

string[]

Fields to include in output

exclude

string[]

Fields to exclude from output

Example

interface AgeStats {
  age: number;
  count: number;
  avg_score: number;
}

const stats = users.aggregate<AgeStats>([
  { match: '[?active == `true`]' },
  { group_by: 'age' },
  { count: 'count' },
  { avg: { field: 'score', output: 'avg_score' } },
  { sort: { field: 'age', asc: true } },
  { limit: 10 }
]);

Watch types

ChangeOperation

Type of change operation.

export type ChangeOperation = 'insert' | 'update' | 'delete';

WatchCallback

Callback function for watching collection changes.

export type WatchCallback<T> = (
  operation: ChangeOperation,
  docId: string,
  document: T | null
) => void;

operation

ChangeOperation

required

Type of operation: 'insert', 'update', or 'delete'

docId

string

required

Document ID that changed

document

T | null

required

The document data (null for delete operations)

Example

const callback: WatchCallback<User> = (op, docId, doc) => {
  switch (op) {
    case 'insert':
      console.log(`New user: ${doc.name}`);
      break;
    case 'update':
      console.log(`Updated user: ${doc.name}`);
      break;
    case 'delete':
      console.log(`Deleted user: ${docId}`);
      break;
  }
};

const handle = users.watch(undefined, callback);

Class types

The following classes are exported and documented in their respective pages:

Database - Main database class
Transaction - Transaction management
Collection - Collection operations
WebServer - Web UI server (stop method only)
WatchHandle - Change watcher handle (stop method only)

WebServer

export class WebServer {
  stop(): void;
}

Returned by db.startWebUi(). Call stop() to shut down the web server.

WatchHandle

export class WatchHandle {
  stop(): void;
}

Returned by collection.watch(). Call stop() to stop watching for changes.

Rust API

Go API

Python API

JavaScript API

Core types

Document

Configuration types

DatabaseOptions

TransactionConfig

Result types

UpsertResult

BulkWriteResult

BulkWriteError

SearchResult

GarbageCollectResult

Information types

DatabaseInfo

CollectionInfo

IndexInfo

BackupInfo

MetricsSnapshot

Operation types

BulkOperation

BulkInsertOp

BulkUpdateOneOp

BulkUpdateManyOp

BulkDeleteOneOp

BulkDeleteManyOp

Aggregation types

AggregationStage

Watch types

ChangeOperation

WatchCallback

Class types

WebServer

WatchHandle

Build docs developers (and LLMs) love

Rust API

Go API

Python API

JavaScript API

​Core types

​Document

​Configuration types

​DatabaseOptions

​TransactionConfig

​Result types

​UpsertResult

​BulkWriteResult

​BulkWriteError

​SearchResult

​GarbageCollectResult

​Information types

​DatabaseInfo

​CollectionInfo

​IndexInfo

​BackupInfo

​MetricsSnapshot

​Operation types

​BulkOperation

​BulkInsertOp

​BulkUpdateOneOp

​BulkUpdateManyOp

​BulkDeleteOneOp

​BulkDeleteManyOp

​Aggregation types

​AggregationStage

​Watch types

​ChangeOperation

​WatchCallback

​Class types

​WebServer

​WatchHandle

Build docs developers (and LLMs) love

Core types

Document

Configuration types

DatabaseOptions

TransactionConfig

Result types

UpsertResult

BulkWriteResult

BulkWriteError

SearchResult

GarbageCollectResult

Information types

DatabaseInfo

CollectionInfo

IndexInfo

BackupInfo

MetricsSnapshot

Operation types

BulkOperation

BulkInsertOp

BulkUpdateOneOp

BulkUpdateManyOp

BulkDeleteOneOp

BulkDeleteManyOp

Aggregation types

AggregationStage

Watch types

ChangeOperation

WatchCallback

Class types

WebServer

WatchHandle