Collection Class

interface Collection<T = Record<string, unknown>> {
  readonly namespace: string
  find(filter?: Filter, options?: FindOptions): Promise<PaginatedResult<Entity<T>>>
  findOne(filter?: Filter, options?: FindOptions): Promise<Entity<T> | null>
  get(id: string, options?: GetOptions): Promise<Entity<T> | null>
  create(data: CreateInput<T>, options?: CreateOptions): Promise<Entity<T>>
  update(id: string, update: UpdateInput<T>, options?: UpdateOptions): Promise<Entity<T> | null>
  delete(id: string, options?: DeleteOptions): Promise<DeleteResult>
  deleteMany(filter: Filter, options?: DeleteOptions): Promise<DeleteResult>
  upsert(filter: Filter, update: UpdateInput<T>, options?: UpsertOptions): Promise<Entity<T> | null>
  upsertMany(items: UpsertManyItem<T>[], options?: UpsertManyOptions): Promise<UpsertManyResult>
}

import { ParqueDB, MemoryBackend } from 'parquedb'

const db = new ParqueDB({ storage: new MemoryBackend() })

// Get a typed collection
interface Post {
  title: string
  content: string
  status: 'draft' | 'published'
}

const posts = db.collection<Post>('posts')

// Access via PascalCase property
const posts = db.Posts

// Access via lowercase property
const users = db.users

readonly namespace: string

const posts = db.collection('posts')
console.log(posts.namespace) // 'posts'

find(filter?: Filter, options?: FindOptions): Promise<PaginatedResult<Entity<T>>>

interface PaginatedResult<T> {
  items: T[]           // Array of matching entities
  total?: number       // Total count (if available)
  nextCursor?: string  // Cursor for next page
  hasMore: boolean     // Whether more results exist
}

// Find all entities
const all = await posts.find()

// Find with simple equality filter
const published = await posts.find({ status: 'published' })

// Find with operators
const popular = await posts.find({
  status: 'published',
  viewCount: { $gte: 1000 },
})

// Find with logical operators
const featured = await posts.find({
  $or: [
    { featured: true },
    { viewCount: { $gte: 10000 } },
  ],
})

// Find with pagination
const page1 = await posts.find({}, { limit: 20 })
const page2 = await posts.find({}, {
  limit: 20,
  cursor: page1.nextCursor
})

// Find with sorting
const recent = await posts.find({}, {
  sort: { createdAt: -1 },
  limit: 10,
})

// Find with projection
const titles = await posts.find({}, {
  project: { title: 1, status: 1 },
})

// Find with time-travel
const pastState = await posts.find({}, {
  asOf: new Date('2024-01-01'),
})

// Find including deleted
const withDeleted = await posts.find({}, {
  includeDeleted: true,
})

findOne(filter?: Filter, options?: FindOptions): Promise<Entity<T> | null>

// Find first matching entity
const post = await posts.findOne({ slug: 'hello-world' })

// Find with sorting (get the most recent)
const latest = await posts.findOne({}, {
  sort: { createdAt: -1 },
})

// Find by email (unique field)
const user = await users.findOne({ email: 'alice@example.com' })

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

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

// Get by short ID (namespace is inferred)
const post = await posts.get('abc123')

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

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

// Get including deleted
const deletedPost = await posts.get('abc123', {
  includeDeleted: true,
})

// Get with projection
const titleOnly = await posts.get('abc123', {
  project: { title: 1 },
})

create(data: CreateInput<T>, options?: CreateOptions): Promise<Entity<T>>

// Create a basic entity
const post = await posts.create({
  $type: 'Post',
  name: 'My First Post',
  title: 'Hello World',
  content: 'This is my first post!',
  status: 'draft',
})

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

// Create with actor for audit
const post = await posts.create({
  $type: 'Post',
  name: 'Admin Post',
  title: 'Announcement',
  content: 'Important news...',
}, {
  actor: 'users/admin' as EntityId,
})

// Create with relationships
const post = await posts.create({
  $type: 'Post',
  name: 'Tech Article',
  title: 'Database Design',
  author: { 'Alice': 'users/alice' },
  categories: {
    'Technology': 'categories/tech',
    'Databases': 'categories/db',
  },
})

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

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

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

// Multiple operators
await posts.update('abc123', {
  $set: { status: 'featured' },
  $inc: { featureCount: 1 },
  $currentDate: { lastFeaturedAt: true },
})

// Array operations
await posts.update('abc123', {
  $push: { tags: 'featured' },
  $addToSet: { categories: 'popular' },
})

// Push with modifiers
await posts.update('abc123', {
  $push: {
    comments: {
      $each: [newComment1, newComment2],
      $position: 0,  // Insert at beginning
      $slice: 100,   // Keep only 100 items
    },
  },
})

// Relationship operations
await posts.update('abc123', {
  $link: {
    author: 'users/alice' as EntityId,
    categories: ['categories/tech', 'categories/db'] as EntityId[],
  },
})

// Unlink relationships
await posts.update('abc123', {
  $unlink: { categories: 'categories/old' as EntityId },
})

// With optimistic concurrency
try {
  await posts.update('abc123', {
    $set: { title: 'New Title' },
  }, {
    expectedVersion: 5,
  })
} catch (error) {
  if (error instanceof VersionConflictError) {
    console.log('Conflict detected, please retry')
  }
}

// Upsert (create if not exists)
await posts.update('new-post', {
  $set: { title: 'New Post' },
  $setOnInsert: {
    $type: 'Post',
    name: 'New Post',
    status: 'draft',
  },
}, {
  upsert: true,
})

// Return document before update
const original = await posts.update('abc123', {
  $set: { status: 'archived' },
}, {
  returnDocument: 'before',
})

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

interface DeleteResult {
  deletedCount: number  // Number of entities deleted (0 or 1)
}

// Soft delete (default)
const result = await posts.delete('abc123')
console.log(result.deletedCount) // 1

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

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

// With actor for audit trail
await posts.delete('abc123', {
  actor: 'users/admin' as EntityId,
})

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

interface DeleteResult {
  deletedCount: number  // Total number of entities deleted
}

// Delete all drafts
const result = await posts.deleteMany({ status: 'draft' })
console.log(`Deleted ${result.deletedCount} drafts`)

// Delete old posts
await posts.deleteMany({
  createdAt: { $lt: new Date('2023-01-01') },
})

// Hard delete spam
await posts.deleteMany(
  { spam: true },
  { hard: true }
)

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

// Upsert user by email
const user = await users.upsert(
  { email: 'alice@example.com' },
  {
    $set: { lastLogin: new Date() },
    $setOnInsert: {
      $type: 'User',
      name: 'Alice',
      role: 'member',
    },
  }
)

// Upsert with increment
const stats = await stats.upsert(
  { date: today },
  {
    $inc: { pageViews: 1 },
    $setOnInsert: {
      $type: 'DailyStats',
      name: `Stats ${today}`,
    },
  }
)

upsertMany(
  items: UpsertManyItem<T>[],
  options?: UpsertManyOptions
): Promise<UpsertManyResult>

interface UpsertManyItem<T> {
  filter: Filter                    // Filter to find existing
  update: UpdateInput<T>            // Update operations
  options?: {
    expectedVersion?: number        // Optimistic concurrency
  }
}

interface UpsertManyResult {
  ok: boolean                 // All operations succeeded
  insertedCount: number       // New entities created
  modifiedCount: number       // Existing entities updated
  matchedCount: number        // Entities matched by filters
  upsertedCount: number       // Total upserted (inserted)
  upsertedIds: EntityId[]     // IDs of new entities
  errors: UpsertManyError[]   // Errors that occurred
}

interface UpsertManyError {
  index: number               // Index of failed item
  filter: Filter              // Filter that was used
  error: Error                // The error
}

// Bulk upsert users
const result = await users.upsertMany([
  {
    filter: { email: 'alice@example.com' },
    update: {
      $set: { name: 'Alice Smith' },
      $setOnInsert: { $type: 'User', role: 'member' },
    },
  },
  {
    filter: { email: 'bob@example.com' },
    update: {
      $set: { name: 'Bob Jones' },
      $setOnInsert: { $type: 'User', role: 'member' },
    },
  },
])

console.log(`Inserted: ${result.insertedCount}`)
console.log(`Modified: ${result.modifiedCount}`)

// Continue on errors
const result = await users.upsertMany(items, {
  ordered: false,  // Don't stop on first error
})

if (!result.ok) {
  for (const error of result.errors) {
    console.error(`Item ${error.index} failed:`, error.error.message)
  }
}

// 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          // Full entity ID (namespace/id)
  $type: string          // Entity type name
  name: string           // Display name
}

interface AuditFields {
  createdAt: Date        // Creation timestamp
  createdBy: EntityId    // Creator ID
  updatedAt: Date        // Last update timestamp
  updatedBy: EntityId    // Last updater ID
  deletedAt?: Date       // Soft delete timestamp
  deletedBy?: EntityId   // Who deleted
  version: number        // Version number
}

interface SortSpec {
  [field: string]: 1 | -1 | 'asc' | 'desc'
}

// Examples:
{ createdAt: -1 }           // Descending
{ createdAt: 'desc' }       // Same as above
{ name: 1, createdAt: -1 }  // Multi-field sort

interface Projection {
  [field: string]: 0 | 1 | boolean
}

// Examples:
{ title: 1, content: 1 }  // Include only these
{ password: 0 }           // Exclude this field

type PopulateSpec =
  | string[]                                    // ['author', 'categories']
  | { [predicate: string]: boolean | PopulateOptions }

interface PopulateOptions {
  limit?: number
  sort?: SortSpec
  cursor?: string
  filter?: Filter
  populate?: PopulateSpec  // Nested populate
}

import { VersionConflictError } from 'parquedb'

try {
  await posts.update('abc123',
    { $set: { title: 'New' } },
    { expectedVersion: 5 }
  )
} catch (error) {
  if (error instanceof VersionConflictError) {
    console.log(`Expected ${error.expectedVersion}, got ${error.actualVersion}`)
    // Handle conflict (retry, merge, etc.)
  }
}

try {
  await posts.create({
    $type: 'Post',
    name: 'Test',
    // Missing required 'title' field
  })
} catch (error) {
  console.log(error.message) // 'Missing required field: title'
}

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

const posts = db.collection<Post>('posts')

// Now you get type safety
const post = await posts.create({
  $type: 'Post',
  name: 'My Post',
  title: 'Hello',
  content: 'World',
  status: 'draft',  // TypeScript validates this
  viewCount: 0,
})

async function* getAllPosts() {
  let cursor: string | undefined

  while (true) {
    const result = await posts.find({}, {
      limit: 100,
      cursor,
      sort: { createdAt: -1 },
    })

    for (const post of result.items) {
      yield post
    }

    if (!result.hasMore) break
    cursor = result.nextCursor
  }
}

for await (const post of getAllPosts()) {
  console.log(post.title)
}

async function updateWithRetry(id: string, update: UpdateInput, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const current = await posts.get(id)
    if (!current) throw new Error('Not found')

    try {
      return await posts.update(id, update, {
        expectedVersion: current.version,
      })
    } catch (error) {
      if (error instanceof VersionConflictError && attempt < maxRetries - 1) {
        continue // Retry
      }
      throw error
    }
  }
}

// Prefer upsertMany for bulk operations
const result = await posts.upsertMany(
  items.map(item => ({
    filter: { externalId: item.id },
    update: {
      $set: item.data,
      $setOnInsert: { $type: 'Post', name: item.title },
    },
  })),
  { ordered: false }  // Continue on errors
)