ResolveSpec/resolvespec-js/README.md

ResolveSpec JS

TypeScript client library for ResolveSpec APIs. Supports body-based REST, header-based REST, and WebSocket protocols.

Install

pnpm add @warkypublic/resolvespec-js

Clients

Client	Protocol	Singleton Factory
ResolveSpecClient	REST (body-based)	getResolveSpecClient(config)
HeaderSpecClient	REST (header-based)	getHeaderSpecClient(config)
WebSocketClient	WebSocket	getWebSocketClient(config)

All clients use the class pattern. Singleton factories return cached instances keyed by URL.

REST Client (Body-Based)

Options sent in JSON request body. Maps to Go pkg/resolvespec.

import { ResolveSpecClient, getResolveSpecClient } from '@warkypublic/resolvespec-js';

// Class instantiation
const client = new ResolveSpecClient({ baseUrl: 'http://localhost:3000', token: 'your-token' });

// Or singleton factory (returns cached instance per baseUrl and effective headers)
const client = getResolveSpecClient({ baseUrl: 'http://localhost:3000', token: 'your-token' });

// Read with filters, sort, pagination
const result = await client.read('public', 'users', undefined, {
  columns: ['id', 'name', 'email'],
  filters: [{ column: 'status', operator: 'eq', value: 'active' }],
  sort: [{ column: 'name', direction: 'asc' }],
  limit: 10,
  offset: 0,
  preload: [{ relation: 'Posts', columns: ['id', 'title'] }],
});

// Read by ID
const user = await client.read('public', 'users', 42);

// Create
const created = await client.create('public', 'users', { name: 'New User' });

// Update
await client.update('public', 'users', { name: 'Updated' }, 42);

// Delete
await client.delete('public', 'users', 42);

// Metadata
const meta = await client.getMetadata('public', 'users');

HeaderSpec Client (Header-Based)

Options sent via HTTP headers. Maps to Go pkg/restheadspec.

import { HeaderSpecClient, getHeaderSpecClient } from '@warkypublic/resolvespec-js';

const client = new HeaderSpecClient({ baseUrl: 'http://localhost:3000', token: 'your-token' });
// Or: const client = getHeaderSpecClient({ baseUrl: 'http://localhost:3000', token: 'your-token' });

// GET with options as headers
const result = await client.read('public', 'users', undefined, {
  columns: ['id', 'name'],
  filters: [
    { column: 'status', operator: 'eq', value: 'active' },
    { column: 'age', operator: 'gte', value: 18, logic_operator: 'AND' },
  ],
  sort: [{ column: 'name', direction: 'asc' }],
  limit: 50,
  preload: [{ relation: 'Department', columns: ['id', 'name'] }],
});

// POST create
await client.create('public', 'users', { name: 'New User' });

// PUT update
await client.update('public', 'users', '42', { name: 'Updated' });

// DELETE
await client.delete('public', 'users', '42');

Header Mapping

Header	Options Field	Format
X-Select-Fields	columns	comma-separated
X-Not-Select-Fields	omit_columns	comma-separated
X-FieldFilter-{col}	filters (eq, AND)	value
X-SearchOp-{op}-{col}	filters (AND)	value
X-SearchOr-{op}-{col}	filters (OR)	value
X-Sort	sort	+col asc, -col desc
X-Limit / X-Offset	limit / offset	number
X-Cursor-Forward	cursor_forward	string
X-Cursor-Backward	cursor_backward	string
X-Preload	preload	Rel:col1,col2 pipe-separated
X-Fetch-RowNumber	fetch_row_number	string
X-CQL-SEL-{col}	computedColumns	expression
X-Custom-SQL-W	customOperators	SQL AND-joined

Utility Functions

import { buildHeaders, encodeHeaderValue, decodeHeaderValue } from '@warkypublic/resolvespec-js';

const headers = buildHeaders({ columns: ['id', 'name'], limit: 10 });
// => { 'X-Select-Fields': 'id,name', 'X-Limit': '10' }

const encoded = encodeHeaderValue('complex value');  // 'ZIP_...'
const decoded = decodeHeaderValue(encoded);           // 'complex value'

WebSocket Client

Real-time CRUD with subscriptions. Maps to Go pkg/websocketspec.

import { WebSocketClient, getWebSocketClient } from '@warkypublic/resolvespec-js';

const ws = new WebSocketClient({
  url: 'ws://localhost:8080/ws',
  reconnect: true,
  heartbeatInterval: 30000,
});
// Or: const ws = getWebSocketClient({ url: 'ws://localhost:8080/ws' });

await ws.connect();

// CRUD
const users = await ws.read('users', { schema: 'public', limit: 10 });
const created = await ws.create('users', { name: 'New' }, { schema: 'public' });
await ws.update('users', '1', { name: 'Updated' });
await ws.delete('users', '1');

// Subscribe to changes
const subId = await ws.subscribe('users', (notification) => {
  console.log(notification.operation, notification.data);
});

// Unsubscribe
await ws.unsubscribe(subId);

// Events
ws.on('connect', () => console.log('connected'));
ws.on('disconnect', () => console.log('disconnected'));
ws.on('error', (err) => console.error(err));

ws.disconnect();

Types

All types align with Go pkg/common/types.go.

Key Types

interface Options {
  columns?: string[];
  omit_columns?: string[];
  filters?: FilterOption[];
  sort?: SortOption[];
  limit?: number;
  offset?: number;
  preload?: PreloadOption[];
  customOperators?: CustomOperator[];
  computedColumns?: ComputedColumn[];
  parameters?: Parameter[];
  cursor_forward?: string;
  cursor_backward?: string;
  fetch_row_number?: string;
}

interface FilterOption {
  column: string;
  operator: Operator | string;
  value: any;
  logic_operator?: 'AND' | 'OR';
}

// Operators: eq, neq, gt, gte, lt, lte, like, ilike, in,
//            contains, startswith, endswith, between,
//            between_inclusive, is_null, is_not_null

interface APIResponse<T> {
  success: boolean;
  data: T;
  metadata?: Metadata;
  error?: APIError;
}

Build

pnpm install
pnpm run build    # dist/index.js (ES) + dist/index.cjs (CJS) + .d.ts
pnpm run test     # vitest
pnpm run lint     # eslint

License

MIT

Custom HTTP headers

Both ResolveSpecClient and HeaderSpecClient (including their factory functions) accept headers in ClientConfig and send them on every HTTP request:

const client = new ResolveSpecClient({
  baseUrl: 'http://localhost:3000',
  token: 'your-token',
  headers: { 'X-Tenant': 'acme' },
});

Header names are merged case-insensitively. Custom headers override the default Content-Type; a supplied token overrides custom Authorization, and HeaderSpec query options override matching custom query headers. Without a token, custom Authorization is preserved. Configuration is copied at construction; create or retrieve a client with new configuration to change headers. Factory clients are cached by URL and effective headers, keeping different tenants and tokens separate.

Grid adapters must forward dataSourceOptions.headers to this headers option.