appwrite-orm

library1.0.0jsnpmunverified

Appwrite ORM v1.0.0 is a TypeScript-first ORM for Appwrite, providing type-safe schemas, auto-migration, validation, indexes, and join support. It runs in both Node.js (>=14) and browser environments. Compared to using the Appwrite SDK directly, it offers declarative schema definitions, automatic migration of collections/attributes/indexes, and built-in validation powered by Zod, reducing boilerplate and runtime errors. The package is actively maintained.

database

npm install appwrite-orm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · APPWRITE-ORM

appwrite-orm

databasejavascriptv1.0.0

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.

AppwriteORM

✓ import { AppwriteORM } from 'appwrite-orm';

✗ const AppwriteORM = require('appwrite-orm');

ESM-only package; CommonJS require() not supported.

createSchema

✓ import { createSchema } from 'appwrite-orm';

✗ import { Schema } from 'appwrite-orm';

Schema factory function, not a class.

StringAttribute

✓ import { StringAttribute } from 'appwrite-orm';

✗ import { String } from 'appwrite-orm';

Use specific attribute types to avoid naming conflicts.

AppwriteORM (default)

✓ import AppwriteORM from 'appwrite-orm';

Also available as default export.

types (e.g., Document)

✓ import type { Document } from 'appwrite-orm';

✗ import { Document } from 'appwrite-orm';

Type-only imports should use `import type` for production code.

Initializes Appwrite client, defines a schema, runs auto-migration, then creates and queries documents.

import { Client } from 'appwrite'; import { AppwriteORM, createSchema, StringAttribute, IntegerAttribute } from 'appwrite-orm'; const client = new Client() .setEndpoint(process.env.APPWRITE_ENDPOINT ?? '') .setProject(process.env.APPWRITE_PROJECT ?? '') .setKey(process.env.APPWRITE_API_KEY ?? ''); const orm = new AppwriteORM(client); const userSchema = createSchema({ name: { type: StringAttribute, required: true }, age: { type: IntegerAttribute, required: false, default: 18 } }); await orm.migrate({ users: userSchema }); const newUser = await orm.create('users', { name: 'Alice', age: 30 }); console.log('Created user:', newUser); const users = await orm.find('users', [['name', '==', 'Alice']]); console.log('Found users:', users);

Debug

Known issues

breakingMajor version zero (0.x) may introduce breaking changes without notice.

fix

Pin to exact version and lockfile.

affects: >=0.0.0 <1.0.0

deprecated`createSchema` with plain objects is deprecated in v2; use `schema()` builder function instead.

fix

Use the new builder: `const userSchema = schema().string('name').required().integer('age').default(18)`

affects: >=2.0.0

gotchaPackage is ESM-only. Requires `"type": "module"` in package.json or `.mjs` extension.

fix

Set `"type": "module"` in `package.json` or rename files to `.mjs`.

affects: >=1.0.0

breakingv2 drops support for Node.js <16.

fix

Update Node.js to version 16 or later.

affects: >=2.0.0

gotchaStringAttribute, IntegerAttribute, etc. are classes; do not instantiate directly. Use via schema.

fix

Pass as type reference, e.g., `type: StringAttribute` not `type: new StringAttribute()`.

affects: >=1.0.0

deprecated`orm.database()` method deprecated in favor of direct `orm.collection()`.

fix

Replace `orm.database('users').create(data)` with `orm.create('users', data)`.

affects: >=1.1.0

Errors

Common errors & fixes

Error: Cannot find module 'appwrite-orm'

Package not installed or ESM not configured.

fix

Run `npm install appwrite-orm appwrite@>=13` and ensure `"type": "module"` in package.json.

TypeError: appwrite_orm_1.AppwriteORM is not a constructor

Using `require()` instead of `import` (ESM package).

fix

Change to `import { AppwriteORM } from 'appwrite-orm'` and ensure project is ESM.

AppwriteException: (404) Collection not found

Schema not migrated before first use.

fix

Call `await orm.migrate({ users: userSchema })` before any CRUD operations.

ValidationError: name is required

Required field missing in data.

fix

Include all `required: true` fields in the create/update data.

Error: Attribute 'age' not defined in schema

Trying to query or insert attribute not declared in schema.

fix

Add `age` to the schema definition via `createSchema` or use dynamic attributes.

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

appwriterequiredPeer dependency: required to interact with Appwrite backend SDK (>=13.0.0)

Agent activity

17 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/raisfeld-ori/appwrite-orm ↗

packageappwrite-orm ↗

homepagehttps://appwrite-orm.readthedocs.io ↗