@monospace/sdk

Fully-typed TypeScript SDK for Monospace.

Features

• Type-safe CRUD — Compile-time validation of queries and mutations
• Smart field selection — Return types infer from what you select
• Deep relations — Filter, sort, and limit nested relations
• Rich filtering — Logical operators, comparison operators, relational filters

Installation

npm install @monospace/sdk

Setup

Option A: Interactive setup

npx @monospace/sdk init

Option B: Manual configuration

Create monospace.config.ts in your project root:

import { defineConfig } from '@monospace/sdk/config';

export default defineConfig({
  url: 'http://localhost:3000',
  project: 'dev',
  output: './src/generated/monospace',  // default location
});

Then generate your types:

npx @monospace/sdk generate

Create a client

// src/client.ts
import { createClient } from './generated/monospace';

export const client = createClient({
  url: 'http://localhost:3000',
  project: 'dev',
  apiKey: '<YOUR-API-KEY>',
});

The generated module exports both createClient and your Schema type.

Regenerating types

After schema changes in Monospace, regenerate your types:

npx @monospace/sdk generate

Your editor will immediately reflect the updated collections, fields, and relations.

Usage

The client exposes fully-typed methods for each collection in your schema. Return types are automatically inferred from your field selection.

// src/example.ts
import { client } from './client';

// Typed collection access - "User" comes from your schema
const users = await client.User.readMany({
  fields: ['id', 'name', 'email'],
});
// users is typed as { id: string; name: string; email: string }[]

// Type-safe filtering
const admins = await client.User.readMany({
  fields: ['id', 'name'],
  filter: { role: { _eq: 'admin' } },
});

// Nested relations with field selection
const posts = await client.Post.readMany({
  fields: ['id', 'title', { author: { fields: ['name'] } }],
});
// posts is typed as { id: string; title: string; author: { name: string } }[]

Documentation

• CRUD Operations — Read, create, update, delete
• Field Selection — Type inference from selections
• Filtering — Operators and logical filters
• Reading Relations — Nested data with filter/sort/limit
• Relational Writes — Nested create/connect/disconnect
• Advanced — Untyped operations, sorting, pagination

Contributing

Running the CLI locally

From the monorepo root:

# Build the SDK package
pnpm --filter @monospace/sdk build

# Run CLI commands (pnpm resolves workspace bins automatically)
pnpm monospace generate
pnpm monospace init

Testing

# Run all SDK tests
pnpm test:sdk

# Run SDK package tests directly
pnpm --filter @monospace/sdk test

Typechecking

Typechecking works without building dependencies thanks to path aliases in the root tsconfig.json:

pnpm --filter @monospace/sdk typecheck