Registry / database / google-spreadsheets-orm

google-spreadsheets-orm

library1.0.3jsnpmunverified

A lightweight Node.js ORM library for Google Sheets that follows the data-mapper pattern, providing strict TypeScript typing and CRUD operations including batch operations. Current version is 1.0.3, released on npm with TypeScript type definitions. It supports multiple authentication methods (GoogleAuth, direct sheet clients), automatic load balancing across multiple auth clients with quota retries, and optional caching (in-memory or custom providers) with automatic cache invalidation on write operations. Differentiators: ORM-style interface with typed models, batch operations support, and built-in caching vs raw Google Sheets API.

database

npm install google-spreadsheets-orm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GOOGLE-SPREADSHEET

google-spreadsheets-orm

databasejavascriptv1.0.3

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.

GoogleSpreadsheetOrm

✓ import { GoogleSpreadsheetOrm } from 'google-spreadsheets-orm'

✗ const GoogleSpreadsheetOrm = require('google-spreadsheets-orm')

ESM-only package (type: module). CommonJS require will not work.

FieldType

✓ import { FieldType } from 'google-spreadsheets-orm'

Exported enum; used in castings config. Ensure TypeScript strict mode.

CacheProvider

✓ import { CacheProvider } from 'google-spreadsheets-orm'

Interface for custom cache implementations. Only needed when providing custom cache.

Initializes GoogleSpreadsheetOrm with Google Auth, defines a typed model, then fetches all rows and creates a new row.

import { GoogleAuth } from 'google-auth-library'; import { GoogleSpreadsheetOrm, FieldType } from 'google-spreadsheets-orm'; interface CustomerModel { id: string; dateCreated: Date; name: string; } const auth = new GoogleAuth({ scopes: 'https://www.googleapis.com/auth/spreadsheets', }); const orm = new GoogleSpreadsheetOrm<CustomerModel>({ spreadsheetId: 'your-spreadsheet-id', sheet: 'customers', auth, castings: { dateCreated: FieldType.DATE, }, }); const customers = await orm.all(); console.log(customers); await orm.create({ id: '1111-2222-3333-4444', dateCreated: new Date(), name: 'Jane Doe', });

Debug

Known issues

breakingESM-only: package uses native ESM and does not support CommonJS require().

fix

Use import syntax. If you must use require(), ensure your project is ESM (type: module) and use dynamic import.

affects: >=1.0.0

gotchaFieldType enum values must match the actual data types in the sheet; otherwise castings may fail silently.

fix

Verify the actual data format in the sheet and map appropriately. For dates, ensure the sheet cells are in a parseable date format.

affects: >=1.0.0

gotchaCache is invalidated on any write operation (create, update, delete). If you have multiple writers, cache may become stale.

fix

Use a shared cache provider (e.g., Redis) and set cacheTtlSeconds appropriately, or disable cache if real-time consistency is required.

affects: >=1.0.0

breakingNode.js >=14 required. Older versions will throw SyntaxError due to ESM syntax.

fix

Upgrade Node.js to version 14 or later.

affects: >=1.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM: Must use import to load ES Module: node_modules/google-spreadsheets-orm/index.js

Package is ESM-only, cannot be required() in CJS context.

fix

Use import syntax or wrap in dynamic import: const { GoogleSpreadsheetOrm } = await import('google-spreadsheets-orm');

TypeError: sheetClients is not a function

Providing sheetClients as a single object instead of an array.

fix

Pass an array: sheetClients: [client] instead of sheetClients: client.

InvalidArgumentException: Invalid FieldType for field dateCreated

FieldType value does not match any known type.

fix

Use one of the values from the FieldType enum, e.g., FieldType.DATE.

Upgrade

Version history

1.0.3latest on npm

Audit

Dependencies

google-auth-libraryoptionalRequired for authentication with Google Sheets API

googleapisrequiredRequired for Google Sheets v4 API client

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/joseffffff/google-spreadsheets-orm ↗

packagegoogle-spreadsheets-orm ↗

homepagehttps://github.com/joseffffff/google-spreadsheets-orm#readme ↗