Atmo Collection

A high-performance collection library for managing database records with buffered writes.

Collection Class

The Collection class is a generic class that provides a type-safe interface for working with database records. It includes features like buffered writes, batch operations, and query capabilities.

Generic Type Parameters

The Collection class takes two generic type parameters:

Collection<SourceRecord extends DataRecord, K extends keyof SourceRecord & RecordId>

Usage Example

// Define a record type
interface UserRecord extends DataRecord {
  id: string;
  name: string;
  email: string;
  age: number;
}

// Define table identity
const USER_TABLE: TableIdentity = {
  table: 'users',
  primaryKey: 'id',
  autoIncrement: false
};

// Create a collection
const userCollection = new Collection<UserRecord, 'id'>({
  tableId: USER_TABLE,
  db: database,
  flushConfig: {
    recordThreshold: 10,
    timeoutMs: 500
  }
}, columns);

// Insert records
const users = new Map<string, UserRecord>();
users.set('user1', {
  id: 'user1',
  name: 'John Doe',
  email: '[email protected]',
  age: 30
});
userCollection.create(users);

// Basic query records
const allUsers = await userCollection.queryAll({
  field: 'age',
  op: '>',
  value: 25
});

// Enhanced query with select properties
const latestUsersBySession = await userCollection.select({
  query: {
    and: [
      { field: 'key', op: '=', value: 'some_key' },
      { field: 'sessionId', op: '=', value: 'current_session_id' }
    ]
  },
  sort: [{ field: 'timestamp', desc: true }],
  limit: 1
});

Enhanced Queries

The Collection class now supports enhanced query capabilities through the queryFull method, which provides more powerful filtering, sorting, and pagination options.

SelectNode Interface

The queryFull method accepts a SelectNode object with the following properties:

interface SelectNode {
  query: QueryNode;       // Filter criteria
  sort?: SortOption[];   // Sorting options
  limit?: number;        // Maximum number of records to return
  offset?: number;       // Number of records to skip
}

interface SortOption {
  field: string;         // Field to sort by
  desc?: boolean;        // Sort in descending order if true
}

Buffer Class

The Buffer class is used internally by the Collection class to manage buffered writes. It queues write operations and flushes them to the database in batches.

BufferCommand

The BufferCommand class encapsulates all command processing logic for database operations. It supports several command types:

• SET: A compound command that can be split into PUT and CREATE commands
• PUT: For inserting or updating records with IDs
• CREATE: For inserting records without IDs
• UPDATE: For updating existing records
• PATCH: For partially updating existing records
• DELETE: For removing records
• COMPOUND: A container for multiple commands

The Buffer system intelligently processes and merges commands to optimize database operations:

// The Buffer automatically handles command processing
const buffer = new Buffer<UserRecord, 'id'>({
  tableId: USER_TABLE,
  recordThreshold: 50,
  flushTimeoutMs: 500,
  onFlush: async (commands) => {
    // Process commands when buffer is flushed
  }
});

// Queue a command
buffer.queue({
  type: RECORD_STATUS.SET,
  records: userRecords
});

// Commands with the same type can be merged
buffer.queue({
  type: RECORD_STATUS.DELETE,
  keys: new Set(['user1', 'user2'])
});