Basic

Creating an Instance

Import GassmaClient from the client generated by npx gassma generate and instantiate it directly. Settings written in the schema — relations, default values, and so on — are already injected.

import { GassmaClient } from "./generated/gassma/schemaClient";

const gassma = new GassmaClient();

You can instantiate it using the same pattern as Prisma.

// Prisma
import { PrismaClient } from "@prisma/client";
const prisma = new PrismaClient();

// GASsma (same pattern)
import { GassmaClient } from "./generated/gassma/schemaClient";
const gassma = new GassmaClient();

If you have set datasource.url in gassma.config.ts (or the datasource block in the schema), the target spreadsheet ID is embedded in the generated client, so no argument is needed.

note

When using the GAS script editor alone without the CLI, the form is new Gassma.GassmaClient(). See Using the GAS Editor.

Accessing Sheets

Each model name becomes a property.

const users = gassma.User.findMany({
  where: { age: { gte: 20 } },
  select: { name: true, email: true },
});

Initialization with Options

The constructor accepts an options object.

const gassma = new GassmaClient({
  id: "SPREAD_SHEET_ID",
  omit: {
    User: { password: true },
  },
});

caution

The generated GassmaClient constructor accepts an options object only. A spreadsheet ID cannot be passed directly — specify it in the id property.

const gassma = new GassmaClient({ id: "SPREAD_SHEET_ID" }); // OK

Constructor Options

Option	Description	In the Generated Client	Reference
id	Spreadsheet ID (uses the active spreadsheet when omitted)	The value you pass takes effect	-
omit	Global omit settings	The value you pass takes effect	Global omit
relations	Relation definitions	Comes from the schema (ignored when passed)	Relation Definition
defaults	Default values for fields	Comes from the schema (ignored when passed)	defaults
updatedAt	Auto-update timestamps	Comes from the schema (ignored when passed)	updatedAt
ignore	Field-level exclusion	Comes from the schema (ignored when passed)	ignore
ignoreSheets	Sheet-level exclusion	Comes from the schema (ignored when passed)	ignore
map	Field name mapping	Comes from the schema (ignored when passed)	map
mapSheets	Sheet name mapping	Comes from the schema (ignored when passed)	map
autoincrement	Auto-increment	Comes from the schema (ignored when passed)	autoincrement
lock	Lock used by $transaction and autoincrement (defaults to LockService.getScriptLock())	The value you pass takes effect	Lock

Schema-Derived Options Override Constructor Arguments

The generated GassmaClient constructor overrides the options with the settings read from schema.prisma. As a result, the options marked "Comes from the schema" in the table above are silently ignored — with no error — when passed to the constructor. Write these settings in schema.prisma instead (see Schema).

caution

The override happens per option; the value you pass is not merged. For example, defaults is replaced wholesale by the settings built from @default in the schema, so every model's defaults you passed to the constructor disappears at once.

const gassma = new GassmaClient({
  defaults: {
    User: { role: "guest" }, // ignored (the @default in schema.prisma is used)
  },
});

id / omit / lock are not overridden, so the values you pass are used as-is. When you pass id, it takes precedence over the spreadsheet ID embedded from the schema.

The override only happens in the GassmaClient generated by the CLI. When using new Gassma.GassmaClient() directly without the CLI, every option takes effect (Using the GAS Editor).

note

strictUndefinedChecks is not a constructor option on the generated client. When using the CLI, enable it via previewFeatures in the generator block; once enabled, the generated client passes it automatically (strictUndefinedChecks / Gassma.skip).

Checking Date Values

GASsma runs as a GAS library in a script context separate from the calling script. As a result, checking a Date value returned by GASsma with instanceof Date evaluates to false. Use Object.prototype.toString instead:

const user = gassma.User.findFirst({ where: { id: 1 } });

user.createdAt instanceof Date;
// => false (a Date crossing the library boundary cannot be checked with instanceof)

Object.prototype.toString.call(user.createdAt) === "[object Date]";
// => true

note

This limitation applies to instanceof on built-in types such as Date. GASsma's exported error classes (e.g., Gassma.GassmaMissingArgumentError) are referenced via the Gassma namespace (the library's global), so they can be checked with instanceof. For details, see the error list.