spreadsheet-orm

library1.0.4jsnpmunverified

spreadsheet-orm v1.0.4 is an ORM for Google Spreadsheets that provides a query builder and schema management layer, turning spreadsheets into database-like tables. It offers schema validation, relationship handling (hasOne/hasMany), and a fluent query builder. Actively maintained, it simplifies working with Google Sheets API by abstracting raw API calls. Differentiators include schema definitions, type-safe querying, and built-in data validation, unlike raw google-spreadsheet packages.

database

npm install spreadsheet-orm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SPREADSHEET-ORM

spreadsheet-orm

databasejavascriptv1.0.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SpreadsheetORM

✓ import { SpreadsheetORM } from 'spreadsheet-orm'

✗ const SpreadsheetORM = require('spreadsheet-orm')

ESM-only since v1, no default export

Schema

✓ import { Schema } from 'spreadsheet-orm'

✗ import Schema from 'spreadsheet-orm'

Named export, not default

QueryBuilder

✓ import { QueryBuilder } from 'spreadsheet-orm'

✗ import { QueryBuilder } from 'spreadsheet-orm/query'

Main export, not a subpath

Initialize ORM with Google credentials, define a schema, and run a query with filters and ordering.

import { SpreadsheetORM, Schema } from 'spreadsheet-orm'; const orm = new SpreadsheetORM({ credentials: JSON.parse(process.env.GOOGLE_CREDENTIALS ?? '{}'), spreadsheetId: process.env.SPREADSHEET_ID ?? '' }); const userSchema = new Schema('users', { id: { type: 'string', required: true }, name: { type: 'string', required: true }, email: { type: 'string' }, created_at: { type: 'date' } }); const userModel = orm.model(userSchema); const users = await userModel.query().where('email', '!=', '').orderBy('created_at', 'desc').limit(10).get(); console.log(users);

Debug

Known issues

breakingv1.0.0 changed the constructor signature: 'auth' option replaced by 'credentials'

fix

Use 'credentials' object instead of 'auth'

affects: <1.0.0

deprecatedMethod 'rawQuery' is deprecated in v1.0.3, use 'query().raw()' instead

fix

Replace rawQuery with query().raw()

affects: >=1.0.3

gotchaDate fields are stored as ISO strings, but moment objects are used internally. Ensure consistent date formatting

fix

Always use moment objects when setting dates, or format as ISO strings

affects: >=1.0.0

gotchaRelationships (hasOne, hasMany) require the related schema to be registered before use

fix

Register all schemas before defining relationships

affects: >=1.0.0

gotchaWorksheet names with spaces are not supported; internal naming uses underscores

fix

Avoid spaces in sheet names

affects: >=1.0.0

breakingBefore v1.0.0, the default export was a class. Now it's a named export

fix

Use named import { SpreadsheetORM }

affects: <1.0.0

Errors

Common errors & fixes

Error: Missing credentials. Provide credentials option.

No Google service account credentials provided

fix

Set GOOGLE_CREDENTIALS environment variable with JSON object containing type, project_id, private_key, client_email

TypeError: schema_1.Schema is not a constructor

Using default import instead of named import for Schema

fix

Use import { Schema } from 'spreadsheet-orm'

SpreadsheetORM is not defined

Using CommonJS require with ESM-only package

fix

Use import { SpreadsheetORM } from 'spreadsheet-orm' or enable ESM in your project

Error: Worksheet "users" not found

Sheet title mismatch: schema name must match sheet title exactly

fix

Ensure spreadsheet has a sheet named exactly as the schema name

Upgrade

Version history

1.0.4latest on npm

Audit

Dependencies

google-spreadsheetrequiredCore dependency for interacting with Google Sheets API

momentoptionalUsed for date handling and formatting

Agent activity

10 hits · last 30 days

node