Skip to main content

Quick Start 🚀

Let's build a task management app with jcell in under 5 minutes.

1. Install​

npm install @sajjadbzn/jcell
# or
bun add @sajjadbzn/jcell

2. Define a Schema​

Schemas define the structure of your documents. They're pure TypeScript — no separate config files.

import { createDB, schema, t, memoryAdapter } from '@sajjadbzn/jcell'

const taskSchema = schema({
  id: t.id(),                                // auto-generated UUID
  title: t.string(),                         // required string
  completed: t.boolean().default(false),     // defaults to false
  priority: t.enum(['low', 'medium', 'high'] as const),
  createdAt: t.date().default(() => new Date()),
})

3. Create a Database​

Choose your storage adapter:

// In-memory (data lost on restart — great for tests)
const db = createDB({ adapter: memoryAdapter() })

// File-based (persists to JSON files — perfect for small apps)
// const db = createDB({ adapter: fileAdapter({ path: './data' }) })

4. Register a Collection​

const tasks = db.collection('tasks', taskSchema)

5. Insert Documents​

const task1 = await tasks.insert({
  title: 'Buy groceries',
  priority: 'medium',
})

console.log(task1)
// { id: 'a1b2c3d4-...', title: 'Buy groceries', completed: false,
//   priority: 'medium', createdAt: Date }

6. Query Documents​

// Get all tasks
const all = await tasks.find()

// Find by filter
const incomplete = await tasks.find({ completed: false })

// Use the query builder
const highPriority = await tasks
  .where('priority').eq('high')
  .where('completed').eq(false)
  .find()

// Get first match
const firstHigh = await tasks
  .where('priority').eq('high')
  .first()

// Count
const total = await tasks.count()
const adminCount = await tasks.count({ role: 'admin' })

7. Update & Delete​

// Update by filter
await tasks.update({ id: task1.id }, { completed: true })

// Delete by filter
await tasks.delete({ id: task1.id })

// Bulk operations
await tasks.updateAll({ priority: 'low' })
await tasks.deleteAll()

Complete Example​

Here's a full working example:

import { createDB, schema, t, memoryAdapter } from '@sajjadbzn/jcell'

// Schema
const taskSchema = schema({
  id: t.id(),
  title: t.string(),
  completed: t.boolean().default(false),
  priority: t.enum(['low', 'medium', 'high'] as const),
  createdAt: t.date().default(() => new Date()),
})

// Database
const db = createDB({ adapter: memoryAdapter() })
const tasks = db.collection('tasks', taskSchema)

// Insert
const t1 = await tasks.insert({ title: 'Learn jcell', priority: 'high' })
const t2 = await tasks.insert({ title: 'Build something cool', priority: 'medium' })

// Query
const all = await tasks.find()
console.log(`Total tasks: ${all.length}`)

const high = await tasks.where('priority').eq('high').first()
console.log(`High priority: ${high?.title}`)

// Update
await tasks.update({ id: t1.id }, { completed: true })

// Aggregate
const avgPriority = await tasks.avg('priority') // not meaningful for strings, but works for numbers!

Next Steps​