Intro

Zero Sources provides a collection of TypeScript libraries and demo apps for building real-time change source implementations. Each library is designed to be composable, reusable, and type-safe.

Core Libraries

@cbnsndwch/zero-contracts

Zero protocol contracts and TypeScript types

@cbnsndwch/zero-source-mongodb

MongoDB change streaming to Zero protocol

Watermark Storage

@cbnsndwch/zero-watermark-zqlite

SQLite-based watermark storage

@cbnsndwch/zero-watermark-nats-kv

NATS KV distributed watermark storage

Demo Apps

@cbnsndwch/zero-nest-synced-queries

Synced query utilities and helpers

@cbnsndwch/zrocket-contracts

ZRocket demo application contracts

Installation

All libraries are available via npm and can be installed with pnpm:

# Install a specific library
pnpm add @cbnsndwch/zero-source-mongodb

# Install multiple libraries
pnpm add @cbnsndwch/zero-source-mongodb @cbnsndwch/zero-watermark-zqlite

Library Organization

Libraries follow a consistent structure:

libs/[library-name]/
├── src/
│   ├── index.ts          # Public API exports
│   ├── types/            # TypeScript type definitions
│   ├── schemas/          # Zero schema definitions
│   └── utils/            # Utility functions
├── package.json
├── tsconfig.json
└── README.md

Choosing Libraries

For Change Sources

zero-source-mongodb: Stream MongoDB changes to Zero
zero-contracts: Common Zero protocol types
zero-watermark-zqlite or zero-watermark-nats-kv: Watermark storage

For NestJS Applications

zero-nest-mongoose: NestJS + Mongoose integration
zero-contracts: Shared types and contracts

For Demo Applications

zrocket-contracts: ZRocket demo schemas and types
synced-queries: Query utilities

Common Patterns

Basic Change Source

import { MongoDBChangeSource } from '@cbnsndwch/zero-source-mongodb';
import { ZQLiteWatermarkStorage } from '@cbnsndwch/zero-watermark-zqlite';
import { schema } from './schema';

const changeSource = new MongoDBChangeSource({
    schema,
    watermarkStorage: new ZQLiteWatermarkStorage(),
    mongoUri: process.env.MONGODB_URI
});

await changeSource.start();

Schema Definition

import { createTableSchema } from '@rocicorp/zero';

export const messageSchema = createTableSchema({
    tableName: 'message',
    columns: {
        id: { type: 'string' },
        content: { type: 'string' }
    },
    primaryKey: ['id']
});

TypeScript Support

All libraries provide full TypeScript support:

Type Definitions: Complete type definitions for all APIs
Generic Types: Leverage TypeScript generics for type safety
Type Inference: Automatic type inference from schemas
Strict Mode: Designed for TypeScript strict mode

Contributing

Want to contribute to a library?

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

See CONTRIBUTING.md for details.