ParqueDB Class

new ParqueDB(config: ParqueDBConfig)

import { ParqueDB, MemoryBackend } from 'parquedb'

const db = new ParqueDB({
  storage: new MemoryBackend(),
  schema: {
    Post: {
      $ns: 'posts',
      title: 'string!',
      content: 'text',
      author: '-> User.posts',
    },
    User: {
      $ns: 'users',
      email: 'email!',
      posts: '<- Post.author[]',
    },
  },
  snapshotConfig: {
    autoSnapshotThreshold: 100,
  },
})

// Get a collection by namespace
const posts = db.collection('posts')
await posts.find({ status: 'published' })

// Or use namespace-based methods directly
await db.find('posts', { status: 'published' })

// Access collections as properties (PascalCase or lowercase)
await db.Posts.find({ status: 'published' })
await db.Users.get('users/123')

registerSchema(schema: Schema): void

db.registerSchema({
  Post: {
    $ns: 'posts',
    title: 'string!',
    content: 'text',
    status: 'string = "draft"',
    author: '-> User.posts',
  },
})

collection<T = Record<string, unknown>>(namespace: string): Collection<T>

interface Post {
  title: string
  content: string
  status: 'draft' | 'published'
}

const posts = db.collection<Post>('posts')
const result = await posts.find({ status: 'published' })

find<T = Record<string, unknown>>(
  namespace: string,
  filter?: Filter,
  options?: FindOptions
): Promise<PaginatedResult<Entity<T>>>

interface PaginatedResult<T> {
  items: T[]
  total?: number
  nextCursor?: string
  hasMore: boolean
}

// Simple filter
const result = await db.find('posts', { status: 'published' })

// With operators
const result = await db.find('posts', {
  score: { $gte: 100 },
  status: { $in: ['published', 'featured'] },
})

// With pagination and sorting
const result = await db.find('posts', {}, {
  sort: { createdAt: -1 },
  limit: 20,
  cursor: lastCursor,
})

// Time-travel query
const result = await db.find('posts', {}, {
  asOf: new Date('2024-01-01'),
})

get<T = Record<string, unknown>>(
  namespace: string,
  id: string,
  options?: GetOptions
): Promise<Entity<T> | null>

// Get by ID
const post = await db.get('posts', 'posts/abc123')

// Get with hydrated relationships
const post = await db.get('posts', 'abc123', {
  hydrate: ['author', 'categories'],
})

// Get historical state
const post = await db.get('posts', 'abc123', {
  asOf: new Date('2024-01-01'),
})

create<T = Record<string, unknown>>(
  namespace: string,
  data: CreateInput<T>,
  options?: CreateOptions
): Promise<Entity<T>>

const post = await db.create('posts', {
  $type: 'Post',
  name: 'My First Post',
  title: 'Hello World',
  content: 'This is my first post.',
  status: 'draft',
}, {
  actor: 'users/admin' as EntityId,
})

console.log(post.$id)       // 'posts/abc123'
console.log(post.version)   // 1
console.log(post.createdAt) // Date

update<T = Record<string, unknown>>(
  namespace: string,
  id: string,
  update: UpdateInput<T>,
  options?: UpdateOptions
): Promise<Entity<T> | null>

// Set fields
const post = await db.update('posts', 'posts/abc123', {
  $set: { status: 'published', publishedAt: new Date() },
})

// Increment counter
await db.update('posts', 'abc123', {
  $inc: { viewCount: 1 },
})

// With optimistic concurrency
await db.update('posts', 'abc123', {
  $set: { title: 'Updated Title' },
}, {
  expectedVersion: 5,
})

// Upsert
await db.update('posts', 'new-post', {
  $set: { title: 'New Post' },
  $setOnInsert: { status: 'draft' },
}, {
  upsert: true,
})

delete(
  namespace: string,
  id: string,
  options?: DeleteOptions
): Promise<DeleteResult>

interface DeleteResult {
  deletedCount: number
}

// Soft delete (default)
const result = await db.delete('posts', 'posts/abc123')

// Hard delete (permanent)
await db.delete('posts', 'abc123', { hard: true })

// With optimistic concurrency
await db.delete('posts', 'abc123', {
  expectedVersion: 5,
})

deleteMany(
  namespace: string,
  filter: Filter,
  options?: DeleteOptions
): Promise<DeleteResult>

// Delete all drafts
const result = await db.deleteMany('posts', { status: 'draft' })
console.log(result.deletedCount) // Number of deleted entities

restore<T = Record<string, unknown>>(
  namespace: string,
  id: string,
  options?: { actor?: EntityId }
): Promise<Entity<T> | null>

const post = await db.restore('posts', 'posts/abc123')

upsert<T = Record<string, unknown>>(
  namespace: string,
  filter: Filter,
  update: UpdateInput<T>,
  options?: { returnDocument?: 'before' | 'after' }
): Promise<Entity<T> | null>

// Find by email or create new user
const user = await db.upsert('users',
  { email: 'user@example.com' },
  {
    $set: { lastLogin: new Date() },
    $setOnInsert: {
      $type: 'User',
      name: 'New User',
      role: 'member',
    },
  }
)

upsertMany<T = Record<string, unknown>>(
  namespace: string,
  items: UpsertManyItem<T>[],
  options?: UpsertManyOptions
): Promise<UpsertManyResult>

const result = await db.upsertMany('users', [
  {
    filter: { email: 'alice@example.com' },
    update: { $set: { name: 'Alice' } },
  },
  {
    filter: { email: 'bob@example.com' },
    update: { $set: { name: 'Bob' } },
  },
])

getRelated<T = Record<string, unknown>>(
  namespace: string,
  id: string,
  relationField: string,
  options?: GetRelatedOptions
): Promise<GetRelatedResult<T>>

// Get posts by a user
const posts = await db.getRelated('users', 'users/123', 'posts', {
  limit: 10,
  sort: { createdAt: -1 },
})

history(
  entityId: EntityId,
  options?: HistoryOptions
): Promise<HistoryResult>

const history = await db.history('posts/abc123' as EntityId, {
  limit: 50,
  op: 'UPDATE',
})

for (const item of history.items) {
  console.log(`${item.op} at ${item.ts} by ${item.actor}`)
}

getHistory(
  namespace: string,
  id: string,
  options?: HistoryOptions
): Promise<HistoryResult>

getAtVersion<T = Record<string, unknown>>(
  namespace: string,
  id: string,
  version: number
): Promise<Entity<T> | null>

// Get the entity as it was at version 3
const post = await db.getAtVersion('posts', 'abc123', 3)

diff(
  entityId: EntityId,
  t1: Date,
  t2: Date
): Promise<DiffResult>

const changes = await db.diff(
  'posts/abc123' as EntityId,
  new Date('2024-01-01'),
  new Date('2024-02-01')
)

console.log('Added fields:', changes.added)
console.log('Changed fields:', changes.changed)
for (const field of changes.changed) {
  const { before, after } = changes.values[field]
  console.log(`  ${field}: ${before} -> ${after}`)
}

revert<T = Record<string, unknown>>(
  entityId: EntityId,
  targetTime: Date,
  options?: RevertOptions
): Promise<Entity<T>>

// Revert to yesterday's state
const post = await db.revert(
  'posts/abc123' as EntityId,
  new Date(Date.now() - 24 * 60 * 60 * 1000)
)

beginTransaction(): ParqueDBTransaction

const tx = db.beginTransaction()

try {
  const post = await tx.create('posts', {
    $type: 'Post',
    name: 'New Post',
    title: 'Transaction Example',
  })

  await tx.update('users', 'users/123', {
    $inc: { postCount: 1 },
  })

  await tx.commit()
} catch (error) {
  await tx.rollback()
  throw error
}

getEventLog(): EventLog

const eventLog = db.getEventLog()

// Get all events for an entity
const events = await eventLog.getEvents('posts/abc123' as EntityId)

// Get events in a time range
const recentEvents = await eventLog.getEventsByTimeRange(
  new Date('2024-01-01'),
  new Date()
)

getSnapshotManager(): SnapshotManager

const snapshots = db.getSnapshotManager()

// Create a snapshot
const snapshot = await snapshots.createSnapshot('posts/abc123' as EntityId)

// List snapshots
const list = await snapshots.listSnapshots('posts/abc123' as EntityId)

// Prune old snapshots
await snapshots.pruneSnapshots({
  olderThan: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000),
  keepMinimum: 5,
})

createIndex(
  ns: string,
  definition: IndexDefinition
): Promise<IndexMetadata>

// Create a hash index for equality lookups
await db.createIndex('orders', {
  name: 'idx_status',
  type: 'hash',
  fields: [{ path: 'status' }],
})

// Create an SST index for range queries
await db.createIndex('products', {
  name: 'idx_price',
  type: 'sst',
  fields: [{ path: 'price' }],
})

// Create an FTS index for full-text search
await db.createIndex('articles', {
  name: 'idx_fts_content',
  type: 'fts',
  fields: [{ path: 'title' }, { path: 'body' }],
})

dropIndex(ns: string, indexName: string): Promise<void>

listIndexes(ns: string): Promise<IndexMetadata[]>

getIndex(ns: string, indexName: string): Promise<IndexMetadata | null>

rebuildIndex(ns: string, indexName: string): Promise<void>

getIndexStats(ns: string, indexName: string): Promise<IndexStats>

getIndexManager(): IndexManager

class VersionConflictError extends Error {
  expectedVersion: number
  actualVersion: number | undefined
}

try {
  await db.update('posts', 'abc123', {
    $set: { title: 'Updated' },
  }, {
    expectedVersion: 5,
  })
} catch (error) {
  if (error instanceof VersionConflictError) {
    console.log(`Expected version ${error.expectedVersion}, got ${error.actualVersion}`)
  }
}

// Entity type properly uses TData for typed data fields
type Entity<TData = Record<string, unknown>> = EntityRef & AuditFields & TData & {
  [key: string]: unknown
}

interface EntityRef {
  $id: EntityId
  $type: string
  name: string
}

interface AuditFields {
  createdAt: Date
  createdBy: EntityId
  updatedAt: Date
  updatedBy: EntityId
  deletedAt?: Date
  deletedBy?: EntityId
  version: number
}

type EntityId = `${string}/${string}` & { readonly __brand: unique symbol }

interface Filter {
  [field: string]: FieldFilter | undefined
  $and?: Filter[]
  $or?: Filter[]
  $not?: Filter
  $nor?: Filter[]
  $text?: TextOperator['$text']
  $vector?: VectorOperator['$vector']
  $geo?: GeoOperator['$geo']
}