open-index/open-npm huggingface dataset:
npm package: @pidgeyjs/cli
Description: CLI toolkit for Pidgey background jobs - migrations, workers, and dashboard
Author: Very Good Building Co.
Latest version: 0.2.0

# @pidgeyjs/cli

CLI tools for managing Pidgey background jobs.

## Installation

```bash
pnpm add -D @pidgeyjs/cli
```

## Usage

```bash
pnpm pidgey <command>
```

## Commands

### `pidgey jobs`

Manage jobs in the queue.

```bash
# View queue status
pnpm pidgey jobs status

# List all jobs
pnpm pidgey jobs list

# List failed jobs
pnpm pidgey jobs list --status failed

# List jobs in a queue
pnpm pidgey jobs list --queue emails
```

### `pidgey jobs retry`

Retry failed jobs.

```bash
pnpm pidgey jobs retry --id <job-id>
pnpm pidgey jobs retry --failed
```

### `pidgey jobs cancel`

Cancel a pending or active job.

```bash
pnpm pidgey jobs cancel --id <job-id>
```

### `pidgey jobs delete`

Delete jobs (single by ID or bulk by filter).

```bash
# Delete a specific job
pnpm pidgey jobs delete --id <job-id>

# Delete all failed jobs
pnpm pidgey jobs delete --status failed

# Delete jobs in a queue
pnpm pidgey jobs delete --queue emails
```

### `pidgey worker`

Manage the background worker.

```bash
# Development mode
pnpm pidgey worker dev

# Production mode
pnpm pidgey worker start
```

### `pidgey schedules`

Manage scheduled (cron) jobs.

```bash
# List scheduled jobs
pnpm pidgey schedules list

# Pause a scheduled job
pnpm pidgey schedules pause <schedule-name>

# Resume a paused scheduled job
pnpm pidgey schedules resume <schedule-name>

# Delete a scheduled job
pnpm pidgey schedules delete <schedule-name>
```

## License

MIT
npm package: @pidgeyjs/cli-tools
Description: Shared CLI utilities for Pidgey CLI tools
Author: Very Good Building Co.
Latest version: 0.1.0

# @pidgeyjs/cli-tools

Shared utilities for Pidgey CLI tools.

## Installation

This package is internal to the Pidgey monorepo and is not intended for public use.

## Usage

This package provides shared utilities for building CLI tools within the Pidgey ecosystem, such as logging, formatting, and common CLI patterns.

## License

MIT
npm package: @pidgeyjs/core
Description: Database-agnostic job queue logic
Author: Very Good Building Co.
Latest version: 0.2.0

# @pidgeyjs/core

Core logic for Pidgey, a type-safe job queue for TypeScript.

## Installation

```bash
pnpm add @pidgeyjs/core
```

## Overview

This package contains the core interfaces, types, and client logic for Pidgey. It is designed to be **adapter-agnostic** and provides the foundation for all Pidgey implementations.

> **Note**: Most users should use integration packages like [`@pidgeyjs/next`](../next) instead of using `@pidgeyjs/core` directly. Integration packages provide convenient helpers and smart defaults for specific frameworks.

## Direct Usage

If you need to use Pidgey outside of Next.js or want full control over initialization:

```typescript
import { PidgeyClient } from '@pidgeyjs/core';
import { PostgresQueueAdapter } from '@pidgeyjs/postgres';

const client = new PidgeyClient(
  new PostgresQueueAdapter({
    connectionString: process.env.DATABASE_URL,
  })
);

await client.connect();

const emailJob = client.defineJob({
  name: 'send-email',
  handler: async (data: { to: string }) => {
    console.log('Sending email to', data.to);
  },
});

await emailJob.enqueue({ to: 'user@example.com' });
```

## Available Adapters

- [`@pidgeyjs/postgres`](../postgres) - PostgreSQL adapter
- [`@pidgeyjs/sqlite`](../sqlite) - SQLite adapter
- [`@pidgeyjs/redis`](../redis) - Redis adapter (powered by BullMQ)

## For Framework Integration Developers

This package exports the core types and interfaces needed to build framework-specific integrations:

- `PidgeyClient` - Main client class
- `QueueAdapter` - Base adapter interface
- `JobDefinition`, `JobHandler`, `Job` - Core type definitions
- `defineWorkerConfig` - Helper for worker configuration

## License

MIT
npm package: @pidgeyjs/next
Description: Next.js integration for Pidgey
Author: Very Good Building Co.
Latest version: 0.2.0

# @pidgeyjs/next

Next.js integration for Pidgey with batteries-included configuration helpers.

## Installation

```bash
pnpm add @pidgeyjs/next @pidgeyjs/core
```

You'll also need an adapter:

```bash
# For PostgreSQL
pnpm add @pidgeyjs/postgres pg

# For SQLite
pnpm add @pidgeyjs/sqlite better-sqlite3

# For Redis
pnpm add @pidgeyjs/redis bullmq ioredis
```

## Quick Start

### 1. Initialize the Client

Create a Pidgey client using the `Pidgey()` helper in `lib/pidgey.ts`:

```typescript
import { Pidgey } from '@pidgeyjs/next';

export const pidgey = Pidgey({
  adapter: 'sqlite',
});
```

**Smart Defaults**: If you don't provide a config, Pidgey uses SQLite in development and throws an error in production (forcing you to configure it properly).

### 2. Define Jobs

Create job handlers in your app:

```typescript
// jobs/email.ts
import { pidgey } from '@/lib/pidgey';

export const sendEmailJob = pidgey.defineJob({
  name: 'send-email',
  handler: async (data: { to: string; subject: string }) => {
    console.log(`Sending email to ${data.to}`);
    // Send email logic here
    return { sent: true };
  },
});
```

### 3. Enqueue Jobs

Use the job definition to enqueue work:

```typescript
// app/api/register/route.ts
import { sendEmailJob } from '@/jobs/email';

export async function POST() {
  await sendEmailJob.enqueue({
    to: 'user@example.com',
    subject: 'Welcome!',
  });

  return Response.json({ success: true });
}
```

## Adapter Configuration

### PostgreSQL

```typescript
import { Pidgey } from '@pidgeyjs/next';

export const pidgey = Pidgey({
  adapter: 'postgres',
  connection: process.env.DATABASE_URL!,
});
```

### SQLite

```typescript
import { Pidgey } from '@pidgeyjs/next';

export const pidgey = Pidgey({
  adapter: 'sqlite',
  filename: './dev.db', // defaults to ':memory:'
});
```

### Redis

```typescript
import { Pidgey } from '@pidgeyjs/next';

export const pidgey = Pidgey({
  adapter: 'redis',
  options: {
    host: 'localhost',
    port: 6379,
  },
});
```

## Running Workers

See the [`@pidgeyjs/cli`](../cli) package for running background workers.

## License

MIT
npm package: @pidgeyjs/postgres
Description: Postgres adapter for Pidgey
Author: Very Good Building Co.
Latest version: 0.2.0

# @pidgeyjs/postgres

PostgreSQL adapter for Pidgey.

## Installation

```bash
pnpm add @pidgeyjs/postgres @pidgeyjs/core pg
```

## Usage

### Configuration

```typescript
import { PidgeyClient } from '@pidgeyjs/core';
import { PostgresQueueAdapter } from '@pidgeyjs/postgres';

const client = new PidgeyClient(
  new PostgresQueueAdapter({
    connectionString: process.env.DATABASE_URL,
    // Optional: schema name (default: public)
    schema: 'my_schema',
  })
);
```

### Migrations

This adapter requires database tables to be created. You can use the Pidgey CLI to manage migrations.

```bash
# Create a new migration
pnpm exec pidgey-devkit create-migration
```

Or you can manually run the SQL files found in `node_modules/@pidgeyjs/postgres/dist/migrations`.

## License

MIT
npm package: @pidgeyjs/sqlite
Description: SQLite adapter for Pidgey
Author: Very Good Building Co.
Latest version: 0.2.0

# @pidgeyjs/sqlite

SQLite adapter for Pidgey.

## Installation

```bash
pnpm add @pidgeyjs/sqlite @pidgeyjs/core better-sqlite3
```

## Usage

### Configuration

```typescript
import { PidgeyClient } from '@pidgeyjs/core';
import { SQLiteQueueAdapter } from '@pidgeyjs/sqlite';

const client = new PidgeyClient(
  new SQLiteQueueAdapter({
    filename: 'path/to/database.sqlite',
  })
);
```

### Migrations

This adapter requires database tables to be created. You can use the Pidgey CLI to manage migrations.

```bash
# Create a new migration
pnpm exec pidgey-devkit create-migration
```

Or you can manually run the SQL files found in `node_modules/@pidgeyjs/sqlite/dist/migrations`.

## License

MIT
npm package: @pidgeyjs/utils
Description: Lightweight runtime utilities for Pidgey
Author: Very Good Building Co.
Latest version: 0.1.0

# Pidgey Utils

Lightweight runtime utilities for Pidgey with zero external dependencies.

## Installation

This package is internal to the Pidgey monorepo.

```bash
# In other packages
pnpm add @pidgeyjs/utils --workspace
```

## Usage

```typescript
import { sleep, formatVersion } from '@pidgeyjs/utils';

// Sleep for 1 second
await sleep(1000);

// Format version numbers
const version = formatVersion(42); // "00042"
```

## Available Utilities

### Async Utilities

- **`sleep(ms: number): Promise<void>`** - Promise-based delay

### Format Utilities

- **`formatVersion(version: number): string`** - Format version numbers with leading zeros (5 digits)

## Design Philosophy

This package contains **runtime utilities only**. It has:

- ✅ Zero external dependencies
- ✅ Minimal bundle size
- ✅ Type-safe utilities
- ❌ No CLI-specific code (see `@pidgeyjs/devkit` for that)

Used by: `@pidgeyjs/core`, `@pidgeyjs/postgres`, `@pidgeyjs/sqlite`, `@pidgeyjs/redis`, and other runtime packages.