Data Structures API

const users = client.getMap<string, User>('users');

// Read a single value by key
const user = users.get('user-123');
// Returns: User | undefined

// Get the full record with timestamp
const record = users.getRecord('user-123');
// Returns: LWWRecord<User> | undefined
// { value: User, timestamp: { millis, counter, nodeId }, ttlMs? }

const users = client.getMap<string, User>('users');

// Create a new entry - returns the created record
const id = crypto.randomUUID();
const record = users.set(id, {
  id,
  name: 'Alice',
  email: 'alice@example.com',
  createdAt: Date.now()
});
// Returns: LWWRecord<User>
// { value: {...}, timestamp: { millis, counter, nodeId } }

// Set with TTL (auto-expires after 1 hour)
const tempRecord = users.set('session-123', sessionData, 3600000);

const users = client.getMap<string, User>('users');

// Delete by key - returns the tombstone record
const tombstone = users.remove('user-123');
// Returns: LWWRecord<User>
// { value: null, timestamp: { millis, counter, nodeId } }

const users = client.getMap<string, User>('users');

// Iterate over all non-deleted entries
for (const [key, value] of users.entries()) {
  console.log(key, value);
}

// Get all keys (including tombstones)
for (const key of users.allKeys()) {
  const record = users.getRecord(key);
  if (record?.value !== null) {
    console.log('Active:', key);
  }
}

// Get the size (total entries including tombstones)
console.log('Total entries:', users.size);

const users = client.getMap<string, User>('users');

// Subscribe to any changes in this map
const unsubscribe = users.onChange(() => {
  console.log('Map changed!');
  // Re-read data as needed
});

// Later: stop listening
unsubscribe();

// For synchronization - merge a remote record
const remoteRecord: LWWRecord<User> = {
  value: { id: 'u1', name: 'Bob' },
  timestamp: { millis: 1678900000, counter: 0, nodeId: 'node-2' }
};

// Returns true if local state was updated
const changed = users.merge('u1', remoteRecord);

const todos = client.getORMap<string, Todo>('todos');

// Add an item to a collection
// Each add() creates a unique entry, even with same key
const record = todos.add('active', { title: 'Write docs', priority: 1 });
// Returns: ORMapRecord
// { value: {...}, timestamp: {...}, tag: "unique-id" }

// Add with TTL (auto-expires)
const tempRecord = todos.add('active', { title: 'Temp task' }, 3600000);

// Add another item with same key (both are preserved)
todos.add('active', { title: 'Fix bugs', priority: 2 });

const todos = client.getORMap<string, Todo>('todos');

// Get all values for a key (returns array)
const activeTodos = todos.get('active');
// Returns: Todo[] (all items added with key 'active')

// Get full records with metadata
const records = todos.getRecords('active');
// Returns: ORMapRecord<Todo>[]
// [{ value: {...}, timestamp: {...}, tag: "..." }, ...]

// Get count of unique keys
console.log('Keys:', todos.size);

// Get total record count across all keys
console.log('Total records:', todos.totalRecords);

const todos = client.getORMap<string, Todo>('todos');

// Remove specific value from a key
// Returns array of removed tags (for sync)
const removedTags = todos.remove('active', todoToRemove);
// Returns: string[] - tags that were removed

// Note: Uses strict equality (===) for matching
// For objects, you need the exact same reference

const todos = client.getORMap<string, Todo>('todos');

// Subscribe to changes
const unsubscribe = todos.onChange(() => {
  console.log('ORMap changed!');
  // Re-read data as needed
});

// Later: stop listening
unsubscribe();

// For synchronization - apply a remote record
const remoteRecord: ORMapRecord<Todo> = {
  value: { title: 'Remote task' },
  timestamp: { millis: 1678900000, counter: 0, nodeId: 'node-2' },
  tag: 'unique-tag-from-remote'
};

// Apply the record (idempotent - ignores if tag is tombstoned)
todos.apply('active', remoteRecord);

// Apply a tombstone (deletion from remote)
todos.applyTombstone('unique-tag-from-remote');

// Get all tombstones (for sync protocol)
const tombstones = todos.getTombstones();
// Returns: string[]

// Query with filters
const query = client.query<Todo>('todos', {
  where: { completed: false },
  sort: { createdAt: 'desc' }
});

// Subscribe to live results
const unsubscribe = query.subscribe((results) => {
  console.log('Matching todos:', results);
});

// Get current snapshot (one-time read)
const snapshot = await query.get();

import { Predicates } from '@topgunbuild/client';

// Complex filtering with predicates
const query = client.query<Product>('products', {
  predicate: Predicates.and(
    Predicates.gt('price', 100),
    Predicates.lt('price', 500),
    Predicates.contains('tags', 'electronics')
  )
});