Collection

The Collection class provides a type-safe, high-level API for working with documents in a specific collection. Collections automatically handle transactions and provide rich querying capabilities.

Getting a collection

Collections are obtained using db.getCollection() with a type parameter:

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

interface User extends Document {
  _id: string;
  name: string;
  email: string;
  age: number;
  active: boolean;
}

const db = Database.open('./my-database.db');
const users = db.getCollection<User>('users');

Collection info

`name()`

Returns the collection name.

name(): string

string

The collection name

Example

const users = db.getCollection<User>('users');
console.log(users.name()); // 'users'

Basic CRUD operations

`insert()`

Inserts a document into the collection.

insert(doc: Omit<T, '_id'>): string

Omit<T, '_id'>

required

Document to insert (without _id field)

string

The auto-generated _id of the inserted document

Example

const userId = users.insert({
  name: 'Alice',
  email: 'alice@example.com',
  age: 30,
  active: true
});

console.log(`User created with ID: ${userId}`);

`findById()`

Finds a document by its ID.

findById(id: string): T | null

string

required

Document ID to find

T | null

The document if found, null otherwise

Example

const user = users.findById('user123');

if (user) {
  console.log(`Found: ${user.name} (${user.email})`);
} else {
  console.log('User not found');
}

`updateById()`

Updates a document by its ID.

updateById(id: string, updates: Partial<T>): void

string

required

Document ID to update

Partial<T>

required

Partial document with fields to update

Example

users.updateById('user123', {
  age: 31,
  email: 'newemail@example.com'
});

`deleteById()`

Deletes a document by its ID.

deleteById(id: string): void

string

required

Document ID to delete

Example

users.deleteById('user123');
console.log('User deleted');

`findAll()`

Retrieves all documents in the collection.

findAll(): T[]

T[]

Array of all documents

Example

const allUsers = users.findAll();
console.log(`Total users: ${allUsers.length}`);

`count()`

Counts all documents in the collection.

count(): number

number

Number of documents

Example

const total = users.count();
console.log(`Total users: ${total}`);

Query operations

`find()`

Finds all documents matching a JMESPath filter.

find(filter: string): T[]

string

required

JMESPath query expression

T[]

Array of matching documents

Example

// Find active users over 25
const activeAdults = users.find('[?active == `true` && age > `25`]');

// Find users with specific email domain
const companyUsers = users.find('[?ends_with(email, `@company.com`)]');

`findOne()`

Finds the first document matching a filter.

findOne(filter: string): T | null

string

required

JMESPath query expression

T | null

The first matching document, or null if none found

Example

const user = users.findOne('[?email == `alice@example.com`]');

if (user) {
  console.log(`Found user: ${user.name}`);
}

`update()`

Updates all documents matching a filter.

update(filter: string, updates: Partial<T>): number

string

required

JMESPath query expression

Partial<T>

required

Fields to update

number

Number of documents updated

Example

// Deactivate all users over 65
const updated = users.update('[?age > `65`]', { active: false });
console.log(`Deactivated ${updated} users`);

`updateOne()`

Updates the first document matching a filter.

updateOne(filter: string, updates: Partial<T>): boolean

string

required

JMESPath query expression

Partial<T>

required

Fields to update

boolean

true if a document was updated, false otherwise

Example

const updated = users.updateOne(
  '[?email == `alice@example.com`]',
  { active: false }
);

if (updated) {
  console.log('User updated');
}

`delete()`

Deletes all documents matching a filter.

delete(filter: string): number

string

required

JMESPath query expression

number

Number of documents deleted

Example

// Delete inactive users
const deleted = users.delete('[?active == `false`]');
console.log(`Deleted ${deleted} inactive users`);

`deleteOne()`

Deletes the first document matching a filter.

deleteOne(filter: string): boolean

string

required

JMESPath query expression

boolean

true if a document was deleted, false otherwise

Example

const deleted = users.deleteOne('[?email == `old@example.com`]');

Upsert operations

`upsertById()`

Inserts or updates a document by ID.

upsertById(id: string, doc: Omit<T, '_id'>): UpsertResult

string

required

Document ID

Omit<T, '_id'>

required

Document data (without _id)

UpsertResult

Result indicating whether document was inserted or updated

Show UpsertResult properties

string

The document ID

boolean

true if inserted, false if updated

Example

const result = users.upsertById('user123', {
  name: 'Alice',
  email: 'alice@example.com',
  age: 30,
  active: true
});

if (result.inserted) {
  console.log('New user created');
} else {
  console.log('Existing user updated');
}

`upsert()`

Inserts or updates the first document matching a filter.

upsert(filter: string, doc: Omit<T, '_id'>): UpsertResult

string

required

JMESPath query expression

Omit<T, '_id'>

required

Document data (without _id)

UpsertResult

Result indicating whether document was inserted or updated

Example

const result = users.upsert(
  '[?email == `bob@example.com`]',
  {
    name: 'Bob',
    email: 'bob@example.com',
    age: 25,
    active: true
  }
);

Bulk operations

`insertMany()`

Inserts multiple documents in a single operation.

insertMany(docs: Omit<T, '_id'>[]): string[]

Omit<T, '_id'>[]

required

Array of documents to insert

string[]

Array of generated document IDs

Example

const ids = users.insertMany([
  { name: 'Alice', email: 'alice@example.com', age: 30, active: true },
  { name: 'Bob', email: 'bob@example.com', age: 25, active: true },
  { name: 'Carol', email: 'carol@example.com', age: 35, active: false }
]);

console.log(`Inserted ${ids.length} users`);

`bulkWrite()`

Executes multiple mixed operations (insert, update, delete) in one call.

bulkWrite(
  operations: BulkOperation<Omit<T, '_id'>>[],
  ordered?: boolean
): BulkWriteResult

BulkOperation<Omit<T, '_id'>>[]

required

Array of bulk operations to execute

boolean

If true, stops on first error. If false, continues on errors. Default: true

BulkWriteResult

Statistics about the bulk operation

Show BulkWriteResult properties

number

Number of documents inserted

number

Number of documents updated

number

Number of documents deleted

string[]

Array of IDs for inserted documents

BulkWriteError[]

Array of errors encountered during bulk operation

Example

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

const operations: BulkOperation<Omit<User, '_id'>>[] = [
  {
    op: 'insert',
    doc: { name: 'Alice', email: 'alice@example.com', age: 30, active: true }
  },
  {
    op: 'update_one',
    filter: '[?email == `bob@example.com`]',
    update: { age: 26 }
  },
  {
    op: 'delete_many',
    filter: '[?active == `false`]'
  }
];

const result = users.bulkWrite(operations);

console.log(`Inserted: ${result.inserted_count}`);
console.log(`Updated: ${result.updated_count}`);
console.log(`Deleted: ${result.deleted_count}`);

if (result.errors.length > 0) {
  console.log('Errors:', result.errors);
}

Advanced queries

`queryWithOptions()`

Performs a query with sorting, pagination, and field projection.

queryWithOptions(
  filter?: string,
  sortField?: keyof T & string,
  sortAsc?: boolean,
  limit?: number,
  skip?: number,
  projectFields?: (keyof T & string)[],
  excludeFields?: (keyof T & string)[]
): T[]

string

JMESPath query expression (optional)

keyof T & string

Field to sort by

boolean

Sort ascending if true, descending if false

number

Maximum number of documents to return

number

Number of documents to skip

(keyof T & string)[]

Fields to include in results

(keyof T & string)[]

Fields to exclude from results

T[]

Array of matching documents

Example

// Get top 10 active users sorted by age (descending), skip first 20
const topUsers = users.queryWithOptions(
  '[?active == `true`]',
  'age',
  false,
  10,
  20
);

// Get users with only name and email fields
const basicInfo = users.queryWithOptions(
  undefined,
  undefined,
  undefined,
  undefined,
  undefined,
  ['name', 'email']
);

`queryCount()`

Counts documents matching a query with pagination.

queryCount(filter?: string, skip?: number, limit?: number): number

string

JMESPath query expression (optional)

number

Number of documents to skip

number

Maximum number of documents to count

number

Number of matching documents

`queryFirst()`

Returns the first document matching a query with optional sorting.

queryFirst(
  filter?: string,
  sortField?: keyof T & string,
  sortAsc?: boolean
): T | null

string

JMESPath query expression (optional)

keyof T & string

Field to sort by

boolean

Sort ascending if true, descending if false

T | null

The first matching document, or null if none found

Example

// Get oldest active user
const oldest = users.queryFirst(
  '[?active == `true`]',
  'age',
  false
);

`distinct()`

Returns unique values for a field.

distinct<K extends keyof T>(field: K): T[K][]

required

Field name to get distinct values for

T[K][]

Array of unique values

Example

// Get all unique ages
const ages = users.distinct('age');
console.log('Unique ages:', ages);

// Get all unique email domains (assuming processing)
const emails = users.distinct('email');

`countDistinct()`

Counts unique values for a field.

countDistinct(field: keyof T): number

keyof T

required

Field name

number

Number of distinct values

Example

const uniqueAges = users.countDistinct('age');
console.log(`${uniqueAges} different ages`);

`countWithQuery()`

Counts documents matching a filter.

countWithQuery(filter?: string): number

string

JMESPath query expression (optional)

number

Number of matching documents

Example

const activeCount = users.countWithQuery('[?active == `true`]');
console.log(`Active users: ${activeCount}`);

Full-text search

`search()`

Performs full-text search on indexed fields.

search(query: string): SearchResult[]

string

required

Search query string

SearchResult[]

Array of search results with scores

Show SearchResult properties

string

Document ID of the matching document

number

Relevance score (higher is more relevant)

Example

// First, create a text index
db.createTextIndex('users', 'name_text_idx', 'name');

// Then search
const results = users.search('alice');

for (const result of results) {
  const user = users.findById(result.doc_id);
  console.log(`${user.name} (score: ${result.score})`);
}

Aggregation

`aggregate()`

Runs an aggregation pipeline on the collection.

aggregate<R>(pipeline: AggregationStage[]): R[]

AggregationStage[]

required

Array of aggregation stages

R[]

Array of aggregation results (shape depends on pipeline)

Example

// Count users by age group
const ageGroups = users.aggregate<{ age: number; count: number }>([
  { match: '[?active == `true`]' },
  { group_by: 'age' },
  { count: 'count' },
  { sort: { field: 'age', asc: true } }
]);

console.log(ageGroups);
// [{ age: 25, count: 5 }, { age: 30, count: 3 }, ...]

// Calculate average age by activity status
const avgAges = users.aggregate<{ active: boolean; avg_age: number }>([
  { group_by: 'active' },
  { avg: { field: 'age', output: 'avg_age' } }
]);

See the Types reference for all available aggregation stages.

Change tracking

`watch()`

Watches for changes to documents in the collection.

watch(filter: string | undefined, callback: WatchCallback<T>): WatchHandle

string | undefined

required

JMESPath filter to watch specific documents, or undefined to watch all

WatchCallback<T>

required

Function called when changes occurCallback signature:

(operation: 'insert' | 'update' | 'delete', docId: string, document: T | null) => void

WatchHandle

Handle to stop watching

Example

// Watch all user changes
const handle = users.watch(undefined, (op, docId, doc) => {
  console.log(`${op}: ${docId}`);
  if (doc) {
    console.log('New data:', doc);
  }
});

// Watch only active users
const activeHandle = users.watch(
  '[?active == `true`]',
  (op, docId, doc) => {
    console.log(`Active user ${op}: ${docId}`);
  }
);

// Stop watching later
handle.stop();
activeHandle.stop();

​Collection

​Getting a collection

​Collection info

​name()

​Basic CRUD operations

​insert()

​findById()

​updateById()

​deleteById()

​findAll()

​count()

​Query operations

​find()

​findOne()

​update()

​updateOne()

​delete()

​deleteOne()

​Upsert operations

​upsertById()

​upsert()

​Bulk operations

​insertMany()

​bulkWrite()

​Advanced queries

​queryWithOptions()

​queryCount()

​queryFirst()

​distinct()

​countDistinct()

​countWithQuery()

​Full-text search

​search()

​Aggregation

​aggregate()

​Change tracking

​watch()

Collection

Getting a collection

Collection info

`name()`

Basic CRUD operations

`insert()`

`findById()`

`updateById()`

`deleteById()`

`findAll()`

`count()`

Query operations

`find()`

`findOne()`

`update()`

`updateOne()`

`delete()`

`deleteOne()`

Upsert operations

`upsertById()`

`upsert()`

Bulk operations

`insertMany()`

`bulkWrite()`

Advanced queries

`queryWithOptions()`

`queryCount()`

`queryFirst()`

`distinct()`

`countDistinct()`

`countWithQuery()`

Full-text search

`search()`

Aggregation

`aggregate()`

Change tracking

`watch()`