Introduction

Overview

@igniter-js/collections is a type-safe ORM for content-driven applications. It gives you a Prisma-like API for working with Markdown, JSON, and YAML files — with full schema validation, lifecycle hooks, declarative views, and TypeScript autocomplete everywhere.

You define your content schema once using Zod, and collections infers the entire API surface. No code generation. No boilerplate. No surprises.

Key Features

• Prisma-like API — create, findUnique, findMany, update, delete, count with full TypeScript inference
• Schema Validation — Zod schemas validate frontmatter at runtime, catching errors before files hit disk
• Lifecycle Hooks — onCreated, onUpdated, onDeleted, onRead, onList with cancel support (return false)
• Rich Querying — Filter operators (gte, contains, has), dot-notation nested access, full-text search
• Declarative Views — Define data hooks, component trees, and actions in pure TypeScript
• Event System — Subscribe to global (created) or scoped (posts:updated) events
• Auto-Discovery — Watch directories for .schema.{ts,json} and .view.{ts,json} files with hot reload
• Context Injection — Inject dependencies (DB connections, auth) into every hook and view
• Multi-Adapter — Node FS, Bun FS, Redis, S3, or build your own

Architecture

Collections follows the adapter pattern — the same pattern used across the Igniter.js ecosystem. The manager layer handles CRUD, hooks, events, and validation. The adapter layer handles reading and writing files.

graph TD
    A[Your Application] --> B[IgniterCollectionsManager]
    B --> C[Collection Managers]
    C --> D[Hooks & Validation]
    B --> E[Event Emitter]
    B --> F[View Manager]
    B --> G[Schema Registry]
    C --> H[Adapter Interface]
    H --> I[NodeFsAdapter]
    H --> J[BunFsAdapter]
    H --> K[RedisAdapter]
    H --> L[S3Adapter]

Every operation flows through the same pipeline: validate → execute hooks → write/read via adapter → emit events.

Quick Start

Get a type-safe content collection running in under two minutes.

npm install @igniter-js/collections zod

pnpm add @igniter-js/collections zod

yarn add @igniter-js/collections zod

bun add @igniter-js/collections zod

import { IgniterCollections, IgniterCollectionModel } from '@igniter-js/collections';
import { NodeFsAdapter } from '@igniter-js/collections/adapters';
import { z } from 'zod';

const Posts = IgniterCollectionModel.create('posts')
  .withPatterns(['.content/posts/{id}.mdx'])
  .withSchema(z.object({
    title: z.string(),
    description: z.string(),
    published: z.boolean().default(false),
    tags: z.array(z.string()).optional(),
    author: z.string(),
  }))
  .build();

const docs = IgniterCollections.create()
  .withAdapter(new NodeFsAdapter())
  .withBasePath(process.cwd())
  .addCollection(Posts)
  .build();

// Create a post
const post = await docs.posts.create({
  data: {
    title: 'Getting Started with Igniter.js',
    description: 'Learn how to build type-safe content apps',
    published: true,
    tags: ['tutorial', 'typescript'],
    author: 'Felipe Barcelos',
  }
});

console.log('Created:', post.id);
// Created: 9f3e4d2a-8b7c-4e1f-a3d2-9c8b7e6f5a4d

// Query with full type safety
const published = await docs.posts.findMany({
  where: { published: true },
  orderBy: { createdAt: 'desc' as const },
});

You now have a type-safe, validated content store. Every create, update, and findMany call is fully typed — IntelliSense knows your schema fields, and Zod validates every write.

Core Concepts

Real-World Use Cases

Collections powers content-driven applications across many domains:

Next Steps