@an5/orm 1.0.6 → 1.0.8

package/README.md

@@ -1,147 +1,175 @@
-# @an5/orm
-
-SQL Server ORM. Proxy client. CRUD. Vector search. Middleware. Raw queries. Transactions.
-
-## Features
-
--   **Proxy Client.** Model access. `db.modelName` syntax.
--   **CRUD.** `findMany`, `findFirst`, `findUnique`, `create`, `update`, `delete`, `upsert`.
--   **Advanced Queries.** OR/AND, nested relations, aggregates, `groupBy`.
--   **Vector Search.** Native SQL Server `VECTOR_DISTANCE`. In-memory fallback.
--   **Middleware.** Hook ORM operations: logging, auth, validation.
--   **Raw Queries.** `$queryRaw`, `$executeRaw`. Auto `NOLOCK`.
--   **Transactions.** `$transaction`. Rollback support.
--   **Schema Generator.** Parse `.an5` files. Generate TypeScript/Python/.NET code.
-
-## Quick Start
-
-### Installation
-
-```bash
-npm install @an5/orm
-```
-
-### Configuration
-
-```bash
-cp .env.example .env
-# Edit .env. Set DATABASE_URL.
-```
-
-### Development Commands
-
-```bash
-# Generate code from schema
-npx an5 generate
-
-# Push schema to database
-npx an5 db:push
-
-# Pull schema from database
-npx an5 db:pull
-
-# Seed database
-npx an5 db:seed
-
-# Compare schema with database
-npx an5 db:migrate diff
-
-# Run tests
-npm test
-```
-
-## Usage
-
-```typescript
-import { An5ORM } from '@an5/orm';
-
-const db = new An5ORM();
-
-// CRUD Operations
-const users = await db.user.findMany({
-  where: { email: { contains: '@example.com' } },
-  orderBy: { createdAt: 'desc' },
-  take: 10,
-});
-
-const user = await db.user.create({
-  data: { email: 'john@example.com', name: 'John' },
-});
-
-// Relations
-const orders = await db.user.findMany({
-  include: { orders: true },
-});
-
-// Vector Search
-const similar = await db.document.vectorSearch({
-  vector: [0.1, 0.2, 0.3],
-  take: 5,
-  distanceMetric: 'cosine',
-});
-
-// Transactions
-await db.$transaction(async (tx) => {
-  const user = await tx.user.create({ data: { email: 'jane@example.com' } });
-  await tx.order.create({ data: { userId: user.id, total: 100 } });
-});
-
-// Raw Queries
-const results = await db.$queryRaw`SELECT * FROM users WHERE id = ${id}`;
-```
-
-## Schema Definition
-
-Schema files: `.an5`. Path: `an5Schema/`. SQL Server types.
-
-```an5
-model User {
-  id        NVARCHAR(1000) @id @default(uuid())
-  email     NVARCHAR(255)  @unique
-  name      NVARCHAR(255)?
-  createdAt DATETIME2      @default(now())
-  orders    Order[]
-
-  @@map("users")
-}
-
-model Order {
-  id        NVARCHAR(1000) @id @default(uuid())
-  userId    NVARCHAR(1000)
-  total     INT            @default(0)
-  user      User           @relation(fields: [userId], references: [id])
-
-  @@map("orders")
-}
-```
-
-## Supported SQL Server Types
-
-Type mapping: `.an5` to TypeScript.
-
-| Schema Type | TypeScript |
-|-------------|------------|
-| `NVARCHAR(n)`, `VARCHAR(n)`, `CHAR(n)`, `TEXT` | `string` |
-| `INT`, `SMALLINT`, `TINYINT`, `FLOAT`, `REAL`, `DECIMAL`, `NUMERIC` | `number` |
-| `BIGINT` | `number \| bigint` |
-| `BIT` | `boolean` |
-| `DATETIME`, `DATETIME2`, `DATE`, `TIME` | `Date` |
-| `UNIQUEIDENTIFIER` | `string` |
-| `VARBINARY`, `BINARY`, `IMAGE` | `Buffer` |
-
-## Testing
-
-```bash
-# Unit tests
-node test/unit.test.js
-
-# Generator tests
-node test/generator.test.js
-
-# Smoke test
-npm test
-```
-
-## License
-
-MIT
+# @an5/orm
+
+SQL Server ORM. Proxy client. CRUD. Vector search. Middleware. Raw queries. Transactions.
+
+## Features
+
+-   **Proxy Client.** Model access. `db.modelName` syntax.
+-   **CRUD.** `findMany`, `findFirst`, `findUnique`, `create`, `update`, `delete`, `upsert`.
+-   **Advanced Queries.** OR/AND, nested relations, aggregates, `groupBy`.
+-   **Vector Search.** Native SQL Server `VECTOR_DISTANCE`. In-memory fallback.
+-   **Middleware.** Hook ORM operations: logging, auth, validation.
+-   **Raw Queries.** `$queryRaw`, `$executeRaw`. Auto `NOLOCK`.
+-   **Transactions.** `$transaction`. Rollback support.
+-   **Schema Generator.** Parse `.an5` files. Generate TypeScript/Python/.NET code.
+
+## Quick Start
+
+### Installation
+
+#### TypeScript / Node.js
+```bash
+npm install @an5/orm
+```
+
+#### Python
+```bash
+pip install an5-orm
+```
+
+### Configuration
+
+```bash
+cp .env.example .env
+# Edit .env. Set DATABASE_URL.
+```
+
+### Development Commands
+
+Run from the `an5Orm/` repository directory (no separate CLI binary is shipped):
+
+```bash
+# Generate client code from schema
+npm run generate
+
+# Push schema to database
+npm run db:push
+
+# Pull schema from database
+npm run db:pull
+
+# Seed database
+npm run db:seed
+
+# Compare schema with database
+npm run db:migrate diff
+
+# Generate migration SQL / show status
+npm run db:migrate:generate
+npm run db:migrate:status
+
+# Run tests
+npm test
+```
+
+## Usage
+
+```typescript
+import { An5ORM } from '@an5/orm';
+
+const db = new An5ORM();
+```
+
+The default executor reads the `DATABASE_URL` environment variable. Schema metadata
+(model→table mapping, relations, field types) is auto-loaded from the ORM's own generated
+metadata file `an5Metadata.ts` (created by `npm run generate`, configured via
+`outputs.typescript.ormMetadataFile`). The ORM owns this metadata locally — it never
+imports from the generated client package (the client is generated *from* the ORM).
+
+To provide metadata explicitly instead:
+
+```typescript
+import { An5ORM } from '@an5/orm';
+import { modelToTable, relationMap, modelFields } from './an5Metadata';
+
+const db = new An5ORM(undefined, { modelToTable, relationMap, modelFields });
+```
+
+// CRUD Operations
+const users = await db.user.findMany({
+  where: { email: { contains: '@example.com' } },
+  orderBy: { createdAt: 'desc' },
+  take: 10,
+});
+
+const user = await db.user.create({
+  data: { email: 'john@example.com', name: 'John' },
+});
+
+// Relations
+const orders = await db.user.findMany({
+  include: { orders: true },
+});
+
+// Vector Search
+const similar = await db.document.vectorSearch({
+  vector: [0.1, 0.2, 0.3],
+  take: 5,
+  distanceMetric: 'cosine',
+});
+
+// Transactions
+await db.$transaction(async (tx) => {
+  const user = await tx.user.create({ data: { email: 'jane@example.com' } });
+  await tx.order.create({ data: { userId: user.id, total: 100 } });
+});
+
+// Raw Queries
+const results = await db.$queryRaw`SELECT * FROM users WHERE id = ${id}`;
+```
+
+## Schema Definition
+
+Schema files: `.an5`. Path: `an5Schema/`. SQL Server types.
+
+```an5
+model User {
+  id        NVARCHAR(1000) @id @default(uuid())
+  email     NVARCHAR(255)  @unique
+  name      NVARCHAR(255)?
+  createdAt DATETIME2      @default(now())
+  orders    Order[]
+
+  @@map("users")
+}
+
+model Order {
+  id        NVARCHAR(1000) @id @default(uuid())
+  userId    NVARCHAR(1000)
+  total     INT            @default(0)
+  user      User           @relation(fields: [userId], references: [id])
+
+  @@map("orders")
+}
+```
+
+## Supported SQL Server Types
+
+Type mapping: `.an5` to TypeScript.
+
+| Schema Type | TypeScript |
+|-------------|------------|
+| `NVARCHAR(n)`, `VARCHAR(n)`, `CHAR(n)`, `TEXT` | `string` |
+| `INT`, `SMALLINT`, `TINYINT`, `FLOAT`, `REAL`, `DECIMAL`, `NUMERIC` | `number` |
+| `BIGINT` | `number \| bigint` |
+| `BIT` | `boolean` |
+| `DATETIME`, `DATETIME2`, `DATE`, `TIME` | `Date` |
+| `UNIQUEIDENTIFIER` | `string` |
+| `VARBINARY`, `BINARY`, `IMAGE` | `Buffer` |
+
+## Testing
+
+```bash
+# Unit tests
+node test/unit.test.js
+
+# Generator tests
+node test/generator.test.js
+
+# Smoke test
+npm test
+```
+
+## License
+
+MIT

package/dist/an5Metadata.d.ts

@@ -0,0 +1,10 @@
+import type { RelationDef } from "./metadata";
+export declare const modelToTable: Record<string, string>;
+export declare const modelDescriptions: Record<string, string | undefined>;
+export declare const modelFields: Record<string, Record<string, {
+    ts: string;
+    sql: string;
+    description?: string;
+}>>;
+export declare const relationMap: Record<string, Record<string, RelationDef>>;
+//# sourceMappingURL=an5Metadata.d.ts.map

package/dist/an5Metadata.js

@@ -0,0 +1,29 @@
+"use strict";
+// This file is auto-generated. Do not edit directly.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.relationMap = exports.modelFields = exports.modelDescriptions = exports.modelToTable = void 0;
+exports.modelToTable = {
+    embeddingConfig: "[dbo].[embeddingconfigs]",
+    llmConfig: "[dbo].[llmconfigs]",
+    user: "[dbo].[users]",
+    order: "[dbo].[orders]",
+};
+exports.modelDescriptions = {
+    embeddingConfig: "Embedding provider configuration. Stores API keys and model settings for RAG features.",
+    llmConfig: "LLM provider configuration. Stores API keys and model settings for AI features.",
+    user: "Represents a registered user in the database.",
+    order: "Represents a customer order in the system.",
+};
+exports.modelFields = {
+    embeddingConfig: { id: { ts: "string", sql: "NVARCHAR(1000)", description: "Primary key" }, provider: { ts: "string", sql: "NVARCHAR(100)", description: "Embedding provider: openai, cohere, custom" }, apiKey: { ts: "string", sql: "NVARCHAR(4000)", description: "API key for the embedding service" }, model: { ts: "string?", sql: "NVARCHAR(500)", description: "Model name, e.g. text-embedding-3-small" }, endpoint: { ts: "string?", sql: "NVARCHAR(2000)", description: "Custom endpoint URL" }, isActive: { ts: "boolean", sql: "BIT", description: "Whether this config is active" }, createdAt: { ts: "Date", sql: "DATETIME2", description: "Creation timestamp" }, updatedAt: { ts: "Date", sql: "DATETIME2", description: "Last update timestamp" } },
+    llmConfig: { id: { ts: "string", sql: "NVARCHAR(1000)", description: "Primary key" }, provider: { ts: "string", sql: "NVARCHAR(100)", description: "LLM provider: openai, gemini, custom, azure" }, apiKey: { ts: "string", sql: "NVARCHAR(4000)", description: "API key for the LLM provider" }, model: { ts: "string?", sql: "NVARCHAR(500)", description: "Model name, e.g. gpt-4o, gemini-2.5-flash" }, endpoint: { ts: "string?", sql: "NVARCHAR(2000)", description: "Custom endpoint URL" }, isActive: { ts: "boolean", sql: "BIT", description: "Whether this config is active" }, createdAt: { ts: "Date", sql: "DATETIME2", description: "Creation timestamp" }, updatedAt: { ts: "Date", sql: "DATETIME2", description: "Last update timestamp" } },
+    user: { id: { ts: "string", sql: "NVARCHAR(1000)", description: "Primary key for the User table (auto-generated UUID)" }, email: { ts: "string", sql: "NVARCHAR(255)", description: "Unique email address used for login and notifications" }, name: { ts: "string?", sql: "NVARCHAR(255)", description: "Display name of the user" }, createdAt: { ts: "Date", sql: "DATETIME2", description: "Timestamp when the user profile was created" } },
+    order: { id: { ts: "string", sql: "NVARCHAR(1000)", description: "Primary key for the Order table (auto-generated UUID)" }, userId: { ts: "string", sql: "NVARCHAR(1000)", description: "Foreign key linking to the User model who placed the order" }, total: { ts: "number", sql: "INT", description: "Total cost amount of the order" }, createdAt: { ts: "Date", sql: "DATETIME2", description: "The date and time when the order was created." } },
+};
+exports.relationMap = {
+    embeddingConfig: {},
+    llmConfig: {},
+    user: {},
+    order: {},
+};
+//# sourceMappingURL=an5Metadata.js.map

package/dist/an5Orm.d.ts

@@ -1,3 +1,4 @@
+import { An5Metadata } from "./metadata";
 type ExecutorFn = (queryText: string, params?: Record<string, any>) => Promise<any[]>;
 export interface MiddlewareParams {
     model?: string;
@@ -11,8 +12,10 @@ export declare class An5ORM {
     private customExecutor?;
     [key: string]: any;
     private middlewares;
-    constructor(customExecutor?: ExecutorFn | undefined);
+    readonly metadata: An5Metadata;
+    constructor(customExecutor?: ExecutorFn | undefined, metadata?: An5Metadata);
     $use(middleware: Middleware): void;
+    parseWhere(modelName: string, where: any, params: Record<string, any>, prefix?: string): string;
     _executeMiddleware(params: MiddlewareParams, finalAction: (params: MiddlewareParams) => Promise<any>): Promise<any>;
     $connect(): Promise<void>;
     $disconnect(): Promise<void>;