@xata.io/pgstream

TypeScript definitions for pgstream - PostgreSQL streaming and data transformation tool.

Installation

npm install @xata.io/pgstream

Features

• 🔧 CLI Commands - Complete pgstream CLI commands structure
• 🔄 Transformers - All available data transformation functions
• 🏷️ TypeScript Types - Fully typed definitions with const assertions
• ✅ Validation - Built-in Zod validation schemas
• 🔄 Auto-generated - Automatically updated from the latest pgstream definitions

Usage

CLI Commands

import { Commands } from '@xata.io/pgstream';

// Access pgstream CLI commands
console.log(Commands.commands);

// Example: Get all command names
const commandNames = Commands.commands.map((cmd) => cmd.name);
console.log(commandNames); // ['init', 'send', 'schema-dump', ...]

// Example: Find a specific command
const initCommand = Commands.commands.find((cmd) => cmd.name === 'init');
console.log(initCommand?.flags); // Available flags for init command

Data Transformers

import { Transformers } from '@xata.io/pgstream';

// Access available transformers
console.log(Transformers.transformers);

// Example: Get all transformer names
const transformerNames = Transformers.transformers.map((t) => t.name);
console.log(transformerNames); // ['greenmask_boolean', 'greenmask_choice', ...]

// Example: Find transformers by supported type
const stringTransformers = Transformers.transformers.filter((t) => t.supported_types.includes('string'));
console.log(stringTransformers.map((t) => t.name));

// Example: Get transformer parameters
const emailTransformer = Transformers.transformers.find((t) => t.name === 'neosync_email');
console.log(emailTransformer?.parameters); // Available parameters

Source URLs

import { PGSTREAM_CLI_DEFINITION_URL, PGSTREAM_TRANSFORMERS_DEFINITION_URL } from '@xata.io/pgstream';

// Get the source URLs for the definitions
console.log(PGSTREAM_CLI_DEFINITION_URL); // CLI definition URL
console.log(PGSTREAM_TRANSFORMERS_DEFINITION_URL); // Transformers definition URL

Available Transformers

The package includes definitions for various data transformation categories:

Greenmask Transformers

• greenmask_boolean - Boolean value transformation
• greenmask_choice - Random choice from predefined values
• greenmask_date - Date value transformation
• greenmask_firstname - First name generation
• greenmask_float - Floating-point number transformation
• greenmask_integer - Integer value transformation
• greenmask_string - String value transformation
• greenmask_unix_timestamp - Unix timestamp transformation
• greenmask_utc_timestamp - UTC timestamp transformation
• greenmask_uuid - UUID generation

Neosync Transformers

• neosync_email - Email address generation
• neosync_firstname - First name generation
• neosync_fullname - Full name generation
• neosync_lastname - Last name generation
• neosync_string - String generation

Utility Transformers

• json - JSON data transformation
• literal_string - Literal string replacement
• masking - Data masking with various patterns
• phone_number - Phone number generation
• string - Basic string transformation
• template - Template-based transformation

CLI Commands

Available pgstream CLI commands:

• init - Initialize pgstream with replication slot and schema setup
• send - Send data changes to configured destinations
• schema-dump - Dump PostgreSQL schema information
• schema-load - Load schema into pgstream

Each command includes detailed flag definitions, descriptions, and usage examples.

Development

Generate Definitions

To regenerate the TypeScript definitions from the latest pgstream sources:

pnpm run generate

This will fetch the latest definitions from:

• https://raw.githubusercontent.com/xataio/pgstream/main/cli-definition.json
• https://raw.githubusercontent.com/xataio/pgstream/main/transformers-definition.json

Build

pnpm run build

Type Check

pnpm run tsc

Generated Files

• src/cli-definition.ts - pgstream CLI commands definition
• src/transformers-definition.ts - pgstream transformers definition
• src/index.ts - Main exports

Type Safety

All definitions are exported with as const assertions, providing:

• Literal types for string values
• Readonly properties preventing accidental mutations
• IntelliSense support with auto-completion
• Compile-time validation of transformer and command names

// TypeScript will infer exact literal types
type CommandName = (typeof Commands.commands)[number]['name'];
type TransformerName = (typeof Transformers.transformers)[number]['name'];

Related

• pgstream - PostgreSQL streaming and transformation tool
• @xata.io/pgroll - PostgreSQL schema migration definitions

License

Apache-2.0