@jsorm/client

JSORM main runtime. Executes queries and operations.

import { createJsorm } from "@jsorm/client";
import { type DB } from "../.jsorm/types.js";
import { defineConfig } from "@jsorm/core";
import { defineModel, t, r } from "@jsorm/core";
import { createSqliteNodeProvider } from "@jsorm/provider-sqlite-node";
import { schema } from "./jsorm.schema.js";

const User = defineModel("users", {
  db: "main",
  fields: {
    id: t.uuid().primary().autoCreate(),
    name: t.string(100),
    active: t.boolean().default(true),
    createdAt: t.dateTime().autoCreate(),
  },
});

const jsorm = createJsorm<DB>(config, [User], {
  main: (ctx) => createSqliteNodeProvider(ctx.models, { ...ctx.options, schema: schema["main"] }),
});

const users = await jsorm.users.get({
  select: { id: true, name: true },
  where: { active: true },
});

Responsibilities

• createJsorm(config, models, providers) — factory function with Proxy for table access
• ProviderManager — AST → provider routing
• AST builders — AST construction from user input

Does not contain:

• Database drivers
• SQL
• Connections
• Models (only receives them as metadata)

Works on Edge, Serverless, and Node.

API

import { createJsorm } from "@jsorm/client";
import { type DB } from "../.jsorm/types.js";
import { createSqliteNodeProvider } from "@jsorm/provider-sqlite-node";
import { schema } from "./jsorm.schema.js";

const jsorm = createJsorm<DB>(config, models, {
  main: (ctx) => createSqliteNodeProvider(ctx.models, { ...ctx.options, schema: schema["main"] }),
});

Factory function

createJsorm<DB, const TDatabases extends Record<string, DatabaseConfig>>(
  config: ConfigAST<TDatabases>,
  models: readonly RuntimeModel[],
  providers?: Partial<ProviderManifest<TDatabases>>,
): JsormAccessor<DB>

Receives config, models, and the provider manifest. Returns a Proxy that intercepts property access to return TableMethods per table.

The manifest has one key per database declared in jsorm.config.ts, and replaces the requirement to call providers.register once per database. There is no implicit name matching, and omitting a database is legal: the error surfaces on the first query against that database, not at startup.

Table access

// Main database — direct access
jsorm.users.get()
jsorm.users.create({ name: "Ana" })
jsorm.users.update({ where: { id: "1" }, data: { name: "B" } })
jsorm.users.delete({ where: { id: "1" } })

// Non-main database — namespaced
jsorm.cache.users.get()

Instance methods

jsorm.raw(options: { db?: string; sql: string; params?: unknown[] }): Promise<ProviderResult<unknown>>
jsorm.compile(ast: QueryAST, db?: string): { sql: string; params: unknown[] }
jsorm.close(db?: string): Promise<void>
jsorm.syncSchema(db?: string): Promise<ProviderResult<SchemaReport>>
jsorm.getMissingTables(db?: string): Promise<ProviderResult<string[]>>

Properties

jsorm.providers  // ProviderManager — wired by createJsorm from the manifest

Registration with manifest

The third parameter of createJsorm is the provider manifest: one key per declared database, and it replaces the requirement to call providers.register once per database.

import { createSqliteNodeProvider } from "@jsorm/provider-sqlite-node";
import { schema } from "./jsorm.schema.js";

const jsorm = createJsorm<DB>(config, models, {
  main: (ctx) => createSqliteNodeProvider(ctx.models, { ...ctx.options, schema: schema["main"] }),
});

Each factory receives the context of its database (database, access, provider, models, options), so the provider is built with only what belongs to it.

CLI Generated

The runtime is automatically generated via jsorm gen. Do not edit manually.

// src/models/jsorm.server.ts — generated
import { createJsorm } from "@jsorm/client";
import { type DB } from "../../.jsorm/types.js";
import config from "../../jsorm.config.js";
import { createSqliteNodeProvider } from "@jsorm/provider-sqlite-node";
import { schema } from "./jsorm.schema.js";

import { User } from "./server/main/User.js";

const allModels = [User] as const;

const jsorm = createJsorm<DB>(config, allModels, {
  "main": (ctx) => createSqliteNodeProvider(ctx.models, { ...ctx.options, schema: schema["main"] }),
});

export { jsorm, type DB };

ESM-only

Exports .mjs (ESM) with .d.ts types. Does not produce CJS.