spacedrive/packages/ts-client

@spacedrive/client

Type-safe TypeScript client for the Spacedrive daemon, automatically generated from Rust core types using Specta.

Features

• Fully Type-Safe - All types generated directly from Rust core
• Real-time Events - Subscribe to daemon events with full type safety
• Unix Domain Sockets - Direct communication with daemon
• Auto-Generated - Types stay in sync with Rust core automatically
• Rich Documentation - JSDoc comments from Rust code

Installation

npm install @spacedrive/client

Quick Start

import { SpacedriveClient } from '@spacedrive/client';

const client = new SpacedriveClient();

// Test connection
await client.ping();

// Get libraries (fully typed)
const libraries = await client.getLibraries();
console.log('Libraries:', libraries);

// Get jobs with status filtering
const jobs = await client.getJobs('running');
console.log('Running jobs:', jobs);

// Create a new library
const newLibrary = await client.createLibrary('My Photos', '/Users/me/Photos');
console.log('Created library:', newLibrary);

Event Subscription

// Subscribe to specific event types
await client.subscribe(['JobStarted', 'JobProgress', 'JobCompleted']);

// Listen for events (fully typed)
client.on('event', (event) => {
  switch (event) {
    case 'CoreStarted':
      console.log('Daemon started');
      break;
    default:
      if ('JobStarted' in event) {
        console.log(`Job started: ${event.JobStarted.job_type} (${event.JobStarted.job_id})`);
      } else if ('JobProgress' in event) {
        console.log(`Job progress: ${event.JobProgress.progress * 100}%`);
      } else if ('JobCompleted' in event) {
        console.log(`Job completed: ${event.JobCompleted.job_type}`);
        console.log('Output:', event.JobCompleted.output);
      }
      break;
  }
});

client.on('error', (error) => {
  console.error('Client error:', error);
});

client.on('disconnected', () => {
  console.log('Disconnected from daemon');
});

Type Generation

Types are automatically generated from the Rust core using Specta. To regenerate types:

npm run generate-types

API Reference

Core Methods

• ping() - Test daemon connectivity
• executeQuery<Q, R>(query: Q, method: string): Promise<R> - Execute a query operation
• executeAction<A, R>(action: A, method: string): Promise<R> - Execute an action operation
• subscribe(eventTypes?: string[]): Promise<void> - Subscribe to daemon events

Convenience Methods

• getLibraries(includeStats?: boolean): Promise<LibraryInfo[]> - Get all libraries
• createLibrary(name: string, path?: string): Promise<LibraryCreateOutput> - Create a new library
• getJobs(status?: JobStatus): Promise<JobListOutput> - Get job list with optional filtering

Event Types

All event types are fully typed TypeScript unions:

• Event - Main event union type
• JobOutput - Job completion output (adjacently tagged)
• JobStatus - Job status enum ("queued" | "running" | "completed" | ...)
• FileOperation - File operation types
• Progress - Progress information with multiple formats

Architecture

This client uses the same architecture as the Swift client:

1. JSON API Layer - Communicates via JSON instead of bincode for external clients
2. Unix Domain Sockets - Direct, efficient communication with daemon
3. Type Generation - Rust types → TypeScript via Specta
4. Event Streaming - Real-time event subscription with line-delimited JSON

Development

# Install dependencies
npm install

# Build the client
npm run build

# Run tests
npm test

# Watch mode for development
npm run dev