Warp Server ORM

Common errors

• ReferenceError: Reflect is not defined

  cause `reflect-metadata` library was not imported or `emitDecoratorMetadata` is not enabled.
  fix Ensure `import 'reflect-metadata';` is at the top of your main application file and `"emitDecoratorMetadata": true` is in your `tsconfig.json`.

• TypeError: Warp is not a constructor

  cause Attempting to use CommonJS `require()` syntax or incorrect module resolution when `warp-server` is an ES Module.
  fix Use ES Module `import Warp from 'warp-server';` syntax. If using Node.js, ensure your package.json has `"type": "module"` or your file uses the `.mjs` extension, and/or your TypeScript compiler options (`moduleResolution`, `esModuleInterop`) are correctly set for ESM.

Warnings

• breaking Warp Server versions 6.x introduce significant changes and are not backward compatible with versions 5.x or legacy versions. Consult the version-specific documentation to avoid issues.
  Fix: Refer to the `readme-v6.md` (or relevant version) documentation for migration guides and updated API usage. Do not mix dependencies from different major versions.
• gotcha To utilize decorators (e.g., for class and key definitions), your `tsconfig.json` must have `"experimentalDecorators": true` and `"emitDecoratorMetadata": true` configured under `"compilerOptions"`.
  Fix: Add or ensure the presence of `"experimentalDecorators": true` and `"emitDecoratorMetadata": true` in your `tsconfig.json`'s `"compilerOptions"`.
• gotcha The `reflect-metadata` library is a mandatory peer dependency for Warp Server when using TypeScript decorators. It must be installed and imported once at the application's entry point.
  Fix: Install `reflect-metadata` via `npm install --save reflect-metadata` and add `import 'reflect-metadata';` at the very top of your main application file (e.g., `index.ts`).
• gotcha Currently, Warp Server officially supports only MySQL databases. While other adapters are planned, direct usage with other database systems is not supported and will result in errors.
  Fix: Ensure your `databaseURI` is configured for a MySQL connection. Check the documentation for updates on support for other database systems if needed.

Install

• npm install warp-server npm
• yarn add warp-server yarn
• pnpm add warp-server pnpm

Imports

• Warp
  wrong:

  const Warp = require('warp-server');

  correct:

  import Warp from 'warp-server';

  Warp is primarily designed for ESM environments, especially with TypeScript. CommonJS require() may lead to undefined or incorrect module resolution if not configured properly with tools like Babel or TypeScript's `esModuleInterop`.
• Class
  wrong:

  import { Class } from 'warp-server/decorators';

  correct:

  import { Class, Key } from 'warp-server';

  Decorators like `@Class` and `@Key` are used for defining schemas. While often placed in a 'decorators' subpath, the primary module export is indicated here. This import path is inferred based on common ORM patterns and requires review as not explicitly shown in the truncated README.
• reflect-metadata

  import 'reflect-metadata';

  This is a side-effect import and should be done once, ideally at the entry point of your application, to enable decorator metadata emission.

Quickstart

Initializes a Warp service instance with a MySQL database connection, demonstrating the basic setup and asynchronous initialization.

import 'reflect-metadata';
import Warp from 'warp-server';

// Replace with your actual database connection string
const databaseURI = 'mysql://youruser:password@yourserver.com:3306/yourdatabase?charset=utf8';

const service = new Warp({ databaseURI });

async function startService() {
  try {
    await service.initialize();
    console.log('Warp service initialized successfully. You can now define and interact with your models.');
    // Example: You would define your classes and start querying here.
    // @Class()
    // class User {
    //   @Key({ primary: true, autoIncrement: true }) id: number;
    //   @Key() name: string;
    // }
    // service.define(User);
    // const newUser = await service.create(User, { name: 'John Doe' });
    // console.log('New user created:', newUser);
  } catch (error) {
    console.error('Failed to initialize Warp service:', error);
  }
}

startService();