ts-datastore-orm

library2.0.9jsnpmunverified

ts-datastore-orm (v2.0.9) is a TypeScript ORM for Google Cloud Datastore (Firestore in Datastore mode). It provides strong typing, decorators for entity definition, and features like composite indexes, hooks (BeforeInsert, AfterLoad, etc.), and CRUD operations. It has zero runtime dependencies but requires @google-cloud/datastore v5+. Development is active with releases on npm. Key differentiators: type-safe, decorator-based, supports transactions, composite indexes, and lifecycle hooks, with no significant overhead vs native SDK.

database

npm install ts-datastore-orm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TS-DATASTORE-ORM

ts-datastore-orm

databasejavascriptv2.0.9

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.

createConnection

✓ import { createConnection } from 'ts-datastore-orm'

✗ const { createConnection } = require('ts-datastore-orm')

ESM-only; require() will fail unless using Node.js with CJS compatibility.

Entity

✓ import { Entity } from 'ts-datastore-orm'

✗ import { Entity } from 'ts-datastore-orm/dist/Entity'

All exports are at package root; subpath imports are private.

BaseEntity

✓ import { BaseEntity } from 'ts-datastore-orm'

✗ import BaseEntity from 'ts-datastore-orm'

BaseEntity is a named export, not default. Named import is required.

Field

✓ import { Field } from 'ts-datastore-orm'

Decorator for entity fields; used with experimentalDecorators in tsconfig.

Define a User entity with auto-generated ID, create a connection, insert, find, update, and delete a record.

import { createConnection, Entity, Field, BaseEntity, TsDatastoreOrmError } from 'ts-datastore-orm'; @Entity({ namespace: 'test', kind: 'User' }) class User extends BaseEntity { @Field({ generateId: true }) public _id!: number; @Field({ index: true }) public name: string = ''; @Field() public email: string = ''; } async function main() { const conn = await createConnection({ keyFilename: './service-account.json' }); const userRepo = conn.getRepository(User); const user = new User(); user.name = 'Alice'; user.email = 'alice@example.com'; await userRepo.insert(user); const found = await userRepo.findOne({ _id: user._id }); console.log('Found:', found.name); user.name = 'Bob'; await userRepo.update(user); await userRepo.delete(user); } main().catch(console.error);

Debug

Known issues

gotchaClass properties must be initialized with default values (e.g., public name: string = '') or use the definite assignment assertion (!) to avoid TypeScript compile errors with strictPropertyInitialization.

fix

Add default values or use `!` after property name, e.g., `public name!: string`.

affects: >=2.0.0

gotchaThe @Entity decorator's `namespace` option defaults to 'default' if not provided; forgetting to set it may cause entities to land in a different namespace than expected.

fix

Always explicitly set namespace in the @Entity decorator, e.g., @Entity({ namespace: 'my-app', kind: 'User' }).

affects: >=1.0.0

deprecatedUsing `require('ts-datastore-orm')` (CommonJS) will produce a warning in v2 and may break in future versions. The package is ESM-only.

fix

Use ESM imports: `import { ... } from 'ts-datastore-orm'`.

affects: >=2.0.0

gotchaFields with `generateId: true` must be of numeric type; using non-numeric types will cause runtime errors.

fix

Ensure `_id` is typed as `number` and initialized to 0 (or `!`).

affects: >=1.0.0

gotchaThe `@CompositeIndex` decorator only accepts ascending ('asc') or descending ('desc') values; other strings will be ignored.

fix

Use 'asc' or 'desc' for index direction.

affects: >=1.0.0

breakingVersion 2.0.0 removed the `Repository` class's `findById` method; use `findOne({ _id: id })` instead.

fix

Replace `userRepo.findById(123)` with `userRepo.findOne({ _id: 123 })`.

affects: >=2.0.0

Errors

Common errors & fixes

Experimental support for decorators is a feature that is subject to change in a future release. Set the 'experimentalDecorators' option in your 'tsconfig' or 'jsconfig' to remove this warning.

Missing 'experimentalDecorators: true' in tsconfig.json.

fix

Add 'experimentalDecorators': true to compilerOptions in tsconfig.json.

TypeError: Class constructor User cannot be invoked without 'new'

Using ESM import but library exports are not compatible with the module system. Likely using require() for an ESM-only package.

fix

Ensure your project is ESM (type: 'module' in package.json, or use .mjs extension) and use import statements instead of require().

Error: Cannot find module '@google-cloud/datastore'

@google-cloud/datastore is not installed or not in node_modules.

fix

Run: npm install @google-cloud/datastore@latest

TypeError: Cannot read properties of undefined (reading 'datastore')

createConnection() failed due to invalid credentials or environment. The returned connection object is undefined.

fix

Check that keyFilename points to a valid service account JSON file or that clientEmail/privateKey are correct.

Upgrade

Version history

2.0.9latest on npm

Audit

Dependencies

@google-cloud/datastorerequiredRuns Google Cloud Datastore operations; not bundled, must be installed separately.

Agent activity

15 hits · last 30 days

node