@bairock/lenz 0.0.17 → 0.0.19

package/README.md

@@ -4,577 +4,155 @@ GraphQL SDL → MongoDB ORM — TypeScript-клиент и Apollo Server мод
 
 ## Features
 
-- ✅ **GraphQL SDL Schema** — Define models using GraphQL syntax
-- ✅ **TypeScript First** — Full type safety and autocompletion
-- ✅ **MongoDB Only** — Native MongoDB, no SQL
-- ✅ **Prisma Style** — Familiar configuration and client generation
-- ✅ **Auto-generated Client** — Generate TypeScript client from GraphQL schema
-- ✅ **CRUD Modules** — Generate Apollo Server typeDefs + resolvers (`lenz generate crud`)
-- ✅ **Relations Support** — One-to-One, One-to-Many, Many-to-Many
-- ✅ **Smart Loading Strategies** — Automatic choice between populate (separate queries) and lookup (server-side joins)
-- ✅ **Automatic Indexing** — Intelligent index creation for foreign key fields
-- ✅ **Transactions** — ACID transactions with MongoDB
-
-## Сравнение с Prisma
-
-Lenz вдохновлён Prisma, но имеет важные отличия, связанные с MongoDB. Ниже — подробное сравнение.
-
-### Таблица директив
-
-| Prisma атрибут | Lenz директива | Статус |
-|---------------|----------------|--------|
-| `@id` | `@id` | ✅ Полная поддержка (ObjectId) |
-| `@unique` | `@unique` | ✅ Полная поддержка |
-| `@index` | `@index` | ✅ Полная поддержка |
-| `@default(value)` | `@default(value: "...")` | ✅ Полная поддержка |
-| `@default(uuid())` | `@default(generator: "uuid")` | ✅ Эквивалент |
-| `@default(now())` | `@default(generator: "now")` | ✅ Эквивалент |
-| `@default(cuid())` | `@default(generator: "cuid")` | ✅ Базовый CUID |
-| `@default(cuid2())` | `@default(generator: "cuid2")` | ✅ CUID2-совместимый |
-| `@default(autoincrement())` | — | ❌ Не применимо к MongoDB |
-| `@default(dbgenerated())` | — | ❌ Не применимо |
-| `@relation(fields, references)` | `@relation(field)` | ⚠️ Упрощённый синтаксис (одно поле) |
-| `@updatedAt` | `@updatedAt` | ✅ Полная поддержка |
-| `@map` | `@map(name)` | ✅ Полная поддержка |
-| `@@map` | `@modelMap(name)` | ✅ Полная поддержка |
-| `@ignore` | `@ignore` | ✅ Полная поддержка |
-| `@hidden` | `@hide` | ✅ Аналог |
-| `@@unique([a, b])` | `@compoundUnique(fields: [...])` | ✅ Полная поддержка |
-| `@@index([a, b])` | `@compoundIndex(fields: [...])` | ✅ Полная поддержка |
-| `@@id([a, b])` | `@compoundId(fields: [...])` | ✅ Полная поддержка |
-| `@@index([...], type: "text")` | `@fulltext(fields: [...])` | ✅ Эквивалент (MongoDB text index) |
-| `@email` | `@email` | ✅ Полная поддержка |
-| `@url` | `@url` | ✅ Полная поддержка |
-| `@@index(map: "...")` | `@compoundIndex(fields: [...], name: "...")` | ✅ name аргумент |
-| `@id(map: "...")` | `@id(map: "...")` | ✅ Полная поддержка |
-| `@unique(map: "...")` | `@unique(map: "...")` | ✅ Полная поддержка |
-| `@@schema` | — | ❌ Не применимо (multi-schema) |
-| `@@view` | — | ❌ Не реализован |
-| `@relation(onDelete: Restrict)` | `@relation(onDelete: "Restrict")` | ✅ Полная поддержка |
-| `@embedded` (Prisma MongoDB) | `@embedded` | ✅ Полная поддержка |
-| — | `@regex(pattern)` | ✅ Только в Lenz |
-| — | `@@fulltext` | ✅ Только в Lenz (MongoDB text index) |
-
-### Возможности
-
-| Возможность | Prisma | Lenz |
-|------------|--------|------|
-| **Поддерживаемые БД** | PostgreSQL, MySQL, SQLite, MongoDB, SQL Server, CockroachDB | **MongoDB** |
-| **CLI генерация** | `prisma generate` | `lenz generate` |
-| **Schema DSL** | Prisma Schema Language (.prisma) | GraphQL SDL (.graphql) |
-| **Типизация** | Полная (генерация типов) | Полная (генерация типов) |
-| **CRUD** | ✅ | ✅ |
-| **Relations (1:1, 1:m, m:n)** | ✅ | ✅ |
-| **Pagination (offset + cursor)** | ✅ | ✅ |
-| **Transactions** | ✅ | ✅ (требуется replica set) |
-| **Aggregation** | `groupBy`, `aggregate` | Пайплайн MongoDB + `aggregate` |
-| **Raw queries** | `$queryRaw`, `$executeRaw` | `$raw`, `aggregateRaw` |
-| **Client extensions** | `$extends` | `$extends` |
-| **Middleware** | `$use` (удалён в Prisma 6.14) | ❌ (используйте `$extends`) |
-| **Миграции** | Prisma Migrate | ❌ (ленивое создание коллекций) |
-| **Интроспекция** | `prisma db pull` | ❌ |
-| **Seed** | `prisma db seed` | ❌ |
-| **Studio** | Prisma Studio | ❌ |
-| **Драйверы** | Встроенные + driver adapters | MongoDB Native Driver |
-| **Views** | `@@view` (v5+) | ❌ |
-| **Multi-schema** | `@@schema` (PostgreSQL) | ❌ |
-
-### Чего нет в Lenz (но есть в Prisma)
-
-1. **Другие БД** — Lenz поддерживает только MongoDB. Prisma работает с PostgreSQL, MySQL, SQLite, SQL Server, CockroachDB и MongoDB.
-2. **Миграции** — нет аналога Prisma Migrate. Коллекции и индексы создаются лениво при первом подключении.
-3. **Интроспекция** — нет `prisma db pull` для импорта схемы из существующей БД.
-4. **Типы данных** — `Decimal`, `Unsupported("...")` не реализованы. `Bytes` и `BigInt` ✅ реализованы.
-5. **Views** — нет поддержки представлений (`@@view`).
-6. **Seed** — нет встроенного фреймворка для наполнения тестовыми данными.
-7. **Studio** — нет графического редактора данных (аналога Prisma Studio).
-8. **Составные внешние ключи** — `@relation` поддерживает только одно поле, не `fields: [a, b], references: [c, d]`.
-
-### Что есть в Lenz, чего нет в Prisma
-
-1. **`@embedded`** — встроенные документы (MongoDB-специфичная возможность).
-2. **`@hide`** — исключение полей из результатов по умолчанию.
-3. **`@regex(pattern)`** — кастомная валидация через регулярные выражения.
-4. **Стратегии загрузки** — автоматический выбор между `populate` (отдельные запросы) и `lookup` (`$lookup` aggregation) в зависимости от типа связи.
-5. **Гео-пространственные фильтры** — `near`, `nearSphere`, `geoWithin`, `geoIntersects`.
-6. **Атомарные операции с массивами** — `push`, `pull`, `addToSet`, `pop`, `pullAll`, `pushAll`.
-7. **`@fulltext`** — декларативное создание MongoDB text index для полнотекстового поиска.
-8. **Автоматическая инициализация массивов** — обязательные поля-массивы автоматически инициализируются пустым массивом.
-9. **Bytes** — тип `Buffer` для бинарных данных (MongoDB BinData).
-10. **BigInt** — тип `bigint` для 64-битных целых чисел (MongoDB Long).
-
-## CRUD Operations
-
-Lenz provides a comprehensive set of CRUD operations similar to Prisma, with full TypeScript support and MongoDB-native performance.
-
-### Create
-
-**Create a single record:**
-```ts
-const user = await lenz.user.create({
-  data: {
-    email: "elsa@prisma.io",
-    name: "Elsa Prisma",
-  },
-});
-```
-
-**Create multiple records:**
-```ts
-const createMany = await lenz.user.createMany({
-  data: [
-    { name: "Bob", email: "bob@prisma.io" },
-    { name: "Yewande", email: "yewande@prisma.io" },
-  ],
-});
-// Returns: { count: 2 }
-```
-
-### Read
-
-**Get record by ID or unique field:**
-```ts
-// By unique field
-const user = await lenz.user.findUnique({
-  where: { email: "elsa@prisma.io" },
-});
-
-// By ID
-const user = await lenz.user.findUnique({
-  where: { id: "99" },
-});
-```
-
-**Get all records:**
-```ts
-const users = await lenz.user.findMany();
-```
-
-**Get first matching record:**
-```ts
-const user = await lenz.user.findFirst({
-  where: { posts: { some: { likes: { gt: 100 } } } },
-  orderBy: { id: "desc" },
-});
-```
-
-**Filter records:**
-```ts
-// Single field filter
-const users = await lenz.user.findMany({
-  where: { email: { endsWith: "prisma.io" } },
-});
-
-// Multiple conditions with OR/AND
-const users = await lenz.user.findMany({
-  where: {
-    OR: [{ name: { startsWith: "E" } }, { AND: { profileViews: { gt: 0 }, role: "ADMIN" } }],
-  },
-});
-
-// Filter by related records
-const users = await lenz.user.findMany({
-  where: {
-    email: { endsWith: "prisma.io" },
-    posts: { some: { published: false } },
-  },
-});
-```
-
-**Select fields:**
-```ts
-const user = await lenz.user.findUnique({
-  where: { email: "emma@prisma.io" },
-  select: { email: true, name: true },
-});
-// Returns: { email: 'emma@prisma.io', name: "Emma" }
-```
-
-**Include related records:**
-```ts
-const users = await lenz.user.findMany({
-  where: { role: "ADMIN" },
-  include: { posts: true },
-});
-```
-
-### Update
-
-**Update a single record:**
-```ts
-const updateUser = await lenz.user.update({
-  where: { email: "viola@prisma.io" },
-  data: { name: "Viola the Magnificent" },
-});
-```
-
-**Update multiple records:**
-```ts
-const updateUsers = await lenz.user.updateMany({
-  where: { email: { contains: "prisma.io" } },
-  data: { role: "ADMIN" },
-});
-// Returns: { count: 19 }
-```
-
-**Upsert (update or create):**
-```ts
-const upsertUser = await lenz.user.upsert({
-  where: { email: "viola@prisma.io" },
-  update: { name: "Viola the Magnificent" },
-  create: { email: "viola@prisma.io", name: "Viola the Magnificent" },
-});
-```
-
-**Atomic number operations:**
-```ts
-await lenz.post.updateMany({
-  data: {
-    views: { increment: 1 },
-    likes: { increment: 1 },
-  },
-});
-```
-
-### Delete
-
-**Delete a single record:**
-```ts
-const deleteUser = await lenz.user.delete({
-  where: {
-    email: "bert@prisma.io",
-  },
-});
-```
-
-**Delete multiple records:**
-```ts
-const deleteUsers = await lenz.user.deleteMany({
-  where: {
-    email: {
-      contains: "prisma.io",
-    },
-  },
-});
-```
-
-**Delete all records:**
-```ts
-const deleteUsers = await lenz.user.deleteMany({});
-```
-
-**Cascading deletes:** Lenz does not automatically cascade deletes. You must manually delete related records or use transactions:
-
-```ts
-const transaction = await lenz.$transaction([
-  lenz.post.deleteMany({ where: { authorId: "7" } }),
-  lenz.user.delete({ where: { id: "7" } }),
-]);
-```
-
-### Pagination
-
-Lenz supports both offset-based and cursor-based pagination directly in the `findMany` method.
-
-**Offset-based pagination (skip/take):**
-```ts
-// Get records 41-50 (page 5 with 10 per page)
-const users = await lenz.user.findMany({
-  skip: 40,
-  take: 10,
-  where: { /* your filters */ },
-  orderBy: { createdAt: 'desc' }
-});
-```
-
-**Cursor-based pagination (more efficient for large datasets):**
-```ts
-// Get first page (first 10 records)
-const firstPage = await lenz.post.findMany({
-  take: 10,
-  where: { published: true },
-  orderBy: { id: 'asc' },
-});
-
-const lastPost = firstPage[9]; // Last item on page
-const cursor = lastPost?.id; // Use ID as cursor (string)
-
-// Get next page (next 10 records AFTER cursor)
-const nextPage = await lenz.post.findMany({
-  take: 10,
-  skip: 1, // Skip the cursor item itself to avoid duplication
-  cursor: cursor, // Pass cursor as string
-  where: { published: true },
-  orderBy: { id: 'asc' },
-});
-```
-
-**Note:** For cursor-based pagination, the cursor should be the value of the field you're ordering by (typically `id`). The cursor is passed as a string or ObjectId. Ensure the field is unique and sequential.
-
-### Aggregation
-
-Lenz provides direct access to MongoDB aggregation pipeline for complex data analysis, as well as count operations.
-
-**Basic aggregation with MongoDB pipeline:**
-```ts
-const aggregations = await lenz.user.aggregate([
-  { $match: { role: "ADMIN" } },
-  { $group: { _id: "$country", totalViews: { $sum: "$profileViews" } } },
-  { $sort: { totalViews: -1 } }
-]);
-```
-
-**Count operations:**
-```ts
-// Count all users
-const userCount = await lenz.user.count();
-
-// Count with filtering
-const activeUsers = await lenz.user.count({
-  where: { profileViews: { gte: 100 } },
-});
-
-// Count relations (using _count in select)
-const usersWithPostCount = await lenz.user.findMany({
-  select: {
-    _count: {
-      select: { posts: true },
-    },
-  },
-});
-```
-
-**Aggregation with grouping and filtering:**
-```ts
-// Group posts by category and calculate average likes
-const stats = await lenz.post.aggregate([
-  { $match: { published: true } },
-  { $group: {
-      _id: "$categoryId",
-      totalPosts: { $sum: 1 },
-      avgLikes: { $avg: "$likes" },
-      maxLikes: { $max: "$likes" }
-  }},
-  { $sort: { avgLikes: -1 } }
-]);
-```
-
-**Distinct values:**
-```ts
-// Get distinct roles using aggregation
-const distinctRoles = await lenz.user.aggregate([
-  { $group: { _id: "$role" } },
-  { $project: { role: "$_id" } }
-]);
-```
-
-**Note:** The `aggregate()` method accepts raw MongoDB aggregation pipeline stages. For type-safe aggregations, you can define TypeScript interfaces for the aggregation result.
+### Schema & Models
+- GraphQL SDL — модели через `type X @model`
+- 20 директив: `@id`, `@unique`, `@index`, `@default`, `@relation`, `@embedded`, `@createdAt`, `@updatedAt`, `@hide`, `@map`, `@ignore`, `@email`, `@url`, `@regex`, `@modelMap`, `@compoundUnique`, `@compoundIndex`, `@compoundId`, `@fulltext`
+- 11 типов: `String`, `Int`, `Float`, `Boolean`, `ID`, `DateTime`, `Date`, `Json`, `ObjectId`, `Bytes`, `BigInt`
+- Enums, embedded documents, relations (1:1, 1:m, m:n, m:1)
+
+### Generated ORM Client
+- Полная типизация + `.d.ts`
+- CRUD делегаты: `findUnique`, `findFirst`, `findMany`, `create`, `update`, `upsert`, `delete`, `count`, `aggregate`, `groupBy`
+- Nested operations (create/connect/connectOrCreate/disconnect/set/update/delete/upsert)
+- Все Prisma-фильтры: `equals`, `not`, `in`, `lt`/`lte`/`gt`/`gte`, `contains`, `startsWith`, `endsWith`, `mode: insensitive`
+- `AND`/`OR`/`NOT`, массивы (`has`/`hasEvery`/`hasSome`), full-text (`search`), geo-spatial
+- Offset + cursor пагинация (Relay Connection)
+- Атомарные обновления: `$push`/`$pull`/`$addToSet`/`$pop`/`$pullAll` с `$each`/`$position`, `increment`/`decrement`/`multiply`/`divide`
+- Агрегации: `_count`, `_sum`, `_avg`, `_min`, `_max`, `groupBy`
+- Транзакции (ACID), `$extends` (query interception, computed fields), default-генераторы (`uuid`/`now`/`cuid`/`cuid2`/`ulid`)
+- Валидация (`@email`/`@url`/`@regex` с ReDoS), cascade (`Cascade`/`SetNull`/`Restrict`)
+- Две стратегии загрузки: `populate` (eager) и `lookup` (`$lookup`)
+
+### Apollo Server CRUD (`lenz generate crud`)
+- typeDefs + resolvers на каждую модель
+- Резолверы через `{ lenz }` из контекста
+- Баррель `index.ts` — `import { typeDefs, resolvers } from './src'`
+- SDL inputTypes (`*CreateInput`, `*UpdateInput`, все фильтры) в `inputTypes.ts`
+
+### Runtime
+- QueryBuilder — конвертация типизированных запросов в MongoDB
+- Авто-ObjectId (`id` → `_id` с 24-char hex)
+- BSON: ObjectId → string, Long → bigint, Binary → Buffer
+- Logger с уровнями `query`/`info`/`warn`/`error`
+- Типизированные ошибки: `NotFoundError`, `UniqueConstraintError`, `ValidationError`, `ConnectionError`, `TransactionError`
+
+### CLI
+- `lenz init` — создать проект
+- `lenz generate orm` — сгенерировать ORM-клиент
+- `lenz generate crud` — сгенерировать Apollo Server модули
 
 ## Quick Start
 
-### 1. Install Lenz
-
 ```bash
-npm install lenz
-```
-
-### 2. Initialize your project
+# Установка
+npm install @bairock/lenz
 
-```bash
+# Инициализация проекта
 npx lenz init
-```
 
-This creates:
-
-- `lenz/schema.graphql` - Your GraphQL schema
-- `lenz/lenz.config.ts` - Configuration file
-- `.env.example` - Environment variables template
+# Настрой схему в lenz/schema.graphql
+# Сгенерируй ORM-клиент
+npx lenz generate orm
 
-### 3. Edit your schema
+# (опционально) Сгенерируй CRUD для Apollo Server
+npx lenz generate crud
+```
 
-Edit `lenz/schema.graphql`:
+Пример схемы (`lenz/schema.graphql`):
 
 ```graphql
 type User @model {
-  id: ID! @id
+  id: String @id
   email: String! @unique
   name: String!
-
-  # One-to-many relationship (auto-selects lookup strategy)
   posts: [Post!]! @relation(field: "postIds")
-  postIds: [ID!]!  # Array automatically indexed
-
-  # One-to-one relationship (auto-selects populate strategy)
-  profile: Profile @relation(field: "profileId")
-  profileId: ID  # Sparse index automatically created
-
+  postIds: [ID!]!
   createdAt: DateTime! @createdAt
   updatedAt: DateTime! @updatedAt
 }
 
 type Post @model {
-  id: ID! @id
+  id: String @id
   title: String!
   content: String
-
-  # Many-to-one relationship (auto-selects populate strategy)
+  published: Boolean! @default(value: "false")
   author: User! @relation(field: "authorId")
-  authorId: ID!  # Foreign key index automatically created
-
-  # Many-to-many relationship with ID arrays (auto-selects lookup strategy)
-  categories: [Category!]! @relation(field: "categoryIds")
-  categoryIds: [ID!]!  # Multikey index automatically created
+  authorId: ID!
+  tags: [String!]
 }
-
-type Profile @model {
-  id: ID! @id
-  bio: String
-  user: User @relation(field: "userId", strategy: "populate")
-  userId: ID
-}
-
-type Category @model {
-  id: ID! @id
-  name: String! @unique
-  posts: [Post!]! @relation(field: "postIds", strategy: "lookup", index: false)
-  postIds: [ID!]!  # No auto-index (index: false)
-}
-```
-
-### 4. Generate the client
-
-```bash
-npx lenz generate
 ```
 
-This generates the client in `generated/lenz/client`.
-
-### 5. Use in your code
+Использование:
 
 ```typescript
-import { LenzClient } from '../generated/lenz/client';
+import { LenzClient } from '../generated/lenz/client/index.js'
 
-async function main() {
-  const lenz = new LenzClient({
-    url: process.env.MONGODB_URI,
-    database: 'myapp',
-    log: ['query', 'info']  // Enable query logging
-  });
+const lenz = new LenzClient({ url: 'mongodb://localhost:27017/myapp' })
+await lenz.$connect()
 
-  await lenz.$connect();
+// Create
+const user = await lenz.user.create({
+  data: { email: 'test@test.com', name: 'Test' },
+  include: { posts: true }
+})
 
-  // Create a user with posts (populate strategy for posts)
-  const user = await lenz.user.create({
-    data: {
-      email: 'alice@example.com',
-      name: 'Alice',
-      posts: {
-        create: [
-          { title: 'Hello World', content: 'My first post' }
-        ]
-      }
-    },
-    include: {
-      posts: true,      // Uses populate strategy (separate queries)
-      profile: true     // Uses populate strategy (one-to-one)
-    }
-  });
+// Read
+const users = await lenz.user.findMany({
+  where: { email: { contains: 'test' } },
+  orderBy: { createdAt: 'desc' },
+  take: 10
+})
 
-  // Query with include - automatic strategy selection
-  const authorWithBooks = await lenz.author.findUnique({
-    where: { id: 'some-author-id' },
-    include: {
-      books: true       // Uses lookup strategy (one-to-many, single query)
-    }
-  });
+// Update
+await lenz.user.update({
+  where: { id: user.id },
+  data: { name: 'Updated' }
+})
 
-  // Manual array synchronization for lookup strategy
-  // When creating a book, add its ID to author.bookIds
-  const newBook = await lenz.book.create({
-    data: {
-      title: 'New Book',
-      authorId: 'author-id'
-    }
-  });
+// Delete
+await lenz.user.delete({ where: { id: user.id } })
 
-  // Manually update the author's bookIds array
-  await lenz.author.update({
-    where: { id: 'author-id' },
-    data: {
-      bookIds: {
-        push: newBook.id  // Add new book ID to array
-      }
-    }
-  });
+// Transaction
+await lenz.$transaction(async (tx) => {
+  await lenz.user.update({ where: { id: '1' }, data: { name: 'x' } })
+  await lenz.post.create({ data: { title: 'New', authorId: '1' } })
+})
+```
 
-  // Complex query with filtering and sorting
-  const posts = await lenz.post.findMany({
-    where: {
-      title: { contains: 'tutorial' },
-      categories: {
-        some: { name: { equals: 'Programming' } }
-      }
-    },
-    orderBy: { createdAt: 'desc' },
-    take: 10,
-    include: {
-      author: true,      // populate strategy
-      categories: true   // many-to-many lookup strategy (server-side join with $lookup)
-    }
-  });
+## Apollo Server Integration
 
-  // Transaction example (requires replica set)
-  await lenz.$transaction(async (tx) => {
-    const updatedUser = await lenz.user.update({
-      where: { id: user.id },
-      data: { name: 'Alice Updated' }
-    });
+```typescript
+import { ApolloServer } from '@apollo/server'
+import { startStandaloneServer } from '@apollo/server/standalone'
+import { LenzClient } from '../generated/lenz/client/index.js'
+import { typeDefs, resolvers } from './src/index.js'
 
-    await lenz.post.create({
-      data: {
-        title: 'Transaction Post',
-        authorId: user.id
-      }
-    });
-  });
+const lenz = new LenzClient({ url: process.env.MONGO_URL })
+await lenz.$connect()
 
-  // Advanced many-to-many lookup with filtering
-  // Uses MongoDB aggregation pipeline for server-side joins
-  const postsWithTechCategories = await lenz.post.findMany({
-    where: {
-      categories: {
-        some: {
-          name: { equals: 'Technology' }
-        }
-      }
-    },
-    include: {
-      categories: {
-        where: {
-          name: { equals: 'Technology' }
-        }
-      }
-    },
-    orderBy: { createdAt: 'desc' },
-    take: 5
-  });
+const server = new ApolloServer({ typeDefs, resolvers })
+const { url } = await startStandaloneServer(server, {
+  context: async () => ({ lenz }),
+})
+```
 
-  // Note: For lookup strategy, array synchronization is manual
-  // When creating relationships, update both arrays:
-  // await lenz.post.update({ where: { id: postId }, data: { categoryIds: { push: categoryId } } });
-  // await lenz.category.update({ where: { id: categoryId }, data: { postIds: { push: postId } } });
+## CLI
 
-  await lenz.$disconnect();
-}
+```bash
+npx lenz init                    # Создать проект
+npx lenz generate orm            # Сгенерировать ORM-клиент
+npx lenz generate orm --config lenz/lenz.config.ts
+npx lenz generate crud           # Сгенерировать CRUD для Apollo
+npx lenz generate crud --schema ./schema.graphql --output ./src
+npx lenz generate                # Справка по генерации
 ```
 
-## Configuration
-
-### `lenz/lenz.config.ts`
+## Config
 
 ```typescript
+// lenz/lenz.config.ts
 import 'dotenv/config'
-import { defineConfig } from 'lenz/config'
+import { defineConfig } from '@bairock/lenz/config'
 
 export default defineConfig({
   schema: 'schema.graphql',
@@ -586,544 +164,60 @@ export default defineConfig({
     client: {
       output: '../generated/lenz/client',
     },
-  },
-  log: ['query', 'info', 'warn', 'error'] as const,
-})
-```
-
-### `lenz/lenz.config.js` (for JavaScript projects)
-
-For JavaScript projects, use `lenz.config.js` as an ESM module:
-
-```javascript
-// ESM module - lenz.config.js
-import 'dotenv/config';
-
-export default {
-  schema: 'schema.graphql',
-  datasource: {
-    url: process.env.MONGODB_URI || 'mongodb://localhost:27017',
-    database: process.env.MONGODB_DATABASE || 'myapp',
-  },
-  generate: {
-    client: {
-      output: '../generated/lenz/client',
+    crud: {
+      output: './src',
     },
   },
-  log: ['query', 'info', 'warn', 'error'],
-};
-```
-
-> **Note**: Lenz supports only ESM modules for JavaScript projects. The `lenz init` command automatically detects your project type (TypeScript or JavaScript) and creates the appropriate config file (`lenz.config.ts` for TypeScript, `lenz.config.js` for JavaScript). JavaScript config files must use ESM syntax (`export default`).
-
-## GraphQL Directives
-
-Lenz extends GraphQL with custom directives:
-
-- `@model` - Marks a type as a database model
-- `@id` - Marks a field as primary key (auto-generated ObjectId)
-- `@unique` - Creates a unique index
-- `@index` - Creates a regular index
-- `@default(value: "...")` - Sets default value
-- `@relation(field: "...", strategy: "populate|lookup", index: true|false, onDelete: "NoAction|Cascade|SetNull")` - Defines relation with loading strategy, index control, and cascade delete behavior (default: `NoAction`)
-- `@createdAt` - Auto-sets creation timestamp
-- `@updatedAt` - Auto-updates timestamp
-- `@embedded` - Marks a type as embedded document
-- `@hide` - Excludes field from query results by default
-
-## Relations
-
-Lenz implements MongoDB-native relations with explicit foreign key fields and intelligent loading strategies. Each relation type has an optimal default strategy for loading related data (see [Relation Loading Strategies](#relation-loading-strategies) for details).
-
-**Key principles:**
-- Foreign keys must be in the **source model** (the model containing `@relation`)
-- Arrays are automatically initialized for required array fields
-- Indexes are automatically created for foreign key fields (configurable)
-- Loading strategy is automatically selected based on relation type
-
-### Automatic Array Initialization
-
-Required array fields (like `bookIds: [ID!]!`) are automatically initialized with empty arrays `[]` when creating documents. This prevents MongoDB `$in needs an array` errors when querying relations.
-
-```typescript
-// When creating a document, required arrays are automatically set to []
-const author = await lenz.author.create({
-  data: {
-    name: 'John Doe',
-    // bookIds is automatically set to [] even if not provided
-  }
-});
-```
-
-### One-to-Many / Many-to-One
-A bidirectional relationship where one side has an array and the other has a single reference:
-
-```graphql
-type Author @model {
-  id: ID! @id
-  books: [Book!]! @relation(field: "bookIds")  # one-to-many side, auto: lookup strategy
-  bookIds: [ID!]!                               # array automatically indexed (multikey index)
-}
-
-type Book @model {
-  id: ID! @id
-  author: Author! @relation(field: "authorId")  # many-to-one side, auto: populate strategy
-  authorId: ID!                                 # single ID automatically indexed (sparse index)
-}
-```
-
-- **Author → Book (one-to-many):** Uses `lookup` strategy by default (server-side join). Requires manual synchronization of `bookIds` array.
-- **Book → Author (many-to-one):** Uses `populate` strategy by default (separate query). Foreign key `authorId` has automatic sparse index.
-- **Indexes:** Multikey index on `bookIds`, sparse index on `authorId` (created automatically).
-
-### One-to-One (foreign key single ID in source model)
-
-```graphql
-type User @model {
-  id: ID! @id
-  profile: Profile @relation(field: "profileId")  # auto: populate strategy
-  profileId: ID                                   # optional, sparse index
-}
-
-type Profile @model {
-  id: ID! @id
-  user: User @relation(field: "userId", strategy: "populate")  # explicit populate
-  userId: ID                                   # optional, sparse index
-}
-```
-
-- **Strategy:** Uses `populate` by default (separate queries for each side)
-- **Indexes:** Sparse indexes on `profileId` and `userId` (optional fields)
-- **Optional:** Both sides can be optional (nullable IDs)
-- **Bidirectional:** Each side maintains its own foreign key
-
-### Many-to-Many (ID arrays on both sides)
-
-```graphql
-type Post @model {
-  id: ID! @id
-  categories: [Category!]! @relation(field: "categoryIds")  # auto: lookup strategy (default for arrays)
-  categoryIds: [ID!]!                                        # multikey index
-}
-
-type Category @model {
-  id: ID! @id
-  posts: [Post!]! @relation(field: "postIds", strategy: "lookup", index: false)
-  postIds: [ID!]!                                            # no auto-index (index: false)
-}
-```
-
-- **Strategy:** Uses `lookup` by default when foreign key arrays are specified (server-side joins with MongoDB's `$lookup` aggregation), `populate` for join collections
-- **Indexes:** Multikey indexes on both array fields (configurable with `index: false`)
-- **Bidirectional:** Both sides maintain arrays of IDs
-- **Manual sync:** You must manually synchronize both arrays when creating/updating relations (for `lookup` strategy)
-
-**Example - Manual synchronization for many-to-many lookup strategy:**
-
-```typescript
-// Create a post and category
-const post = await lenz.post.create({
-  data: {
-    title: 'My Post',
-    categoryIds: [] // Initialize empty array
-  }
-});
-
-const category = await lenz.category.create({
-  data: {
-    name: 'Technology',
-    postIds: [] // Initialize empty array
-  }
-});
-
-// Add category to post
-await lenz.post.update({
-  where: { id: post.id },
-  data: {
-    categoryIds: {
-      push: category.id // Add category ID to post's array
-    }
-  }
-});
-
-// Add post to category (bidirectional sync)
-await lenz.category.update({
-  where: { id: category.id },
-  data: {
-    postIds: {
-      push: post.id // Add post ID to category's array
-    }
-  }
-});
-```
-
-**Important:** Foreign keys must always be in the **source model** (the model containing the `@relation` directive). Classic one-to-many patterns with foreign keys in target models will cause validation errors.
-
-## Relation Loading Strategies
-
-Lenz automatically chooses the optimal strategy for loading related data, balancing performance and simplicity. You can also explicitly override the strategy.
-
-### Populate Strategy (Default for oneToOne, manyToOne)
-
-Uses separate queries - first fetches the main document, then queries related collections. Best for simple relationships and sharded environments.
-
-```graphql
-type User @model {
-  profile: Profile @relation(field: "profileId", strategy: "populate")
-  profileId: ID
-}
-```
-
-### Lookup Strategy (Default for oneToMany)
-
-Uses MongoDB's `$lookup` aggregation operator for server-side joins. Best for high-read scenarios with bidirectional relationships.
-
-```graphql
-type Author @model {
-  books: [Book!]! @relation(field: "bookIds", strategy: "lookup")
-  bookIds: [ID!]!
-}
-```
-
-**Note:** When using `lookup` strategy, you must manually synchronize ID arrays (e.g., `bookIds`) when creating/updating/deleting related documents.
-
-**Include options support:** Lookup strategy now supports `where`, `orderBy`, `take`, and `skip` options for filtering, sorting, and paginating related documents.
-
-Example:
-```typescript
-const author = await lenz.author.findUnique({
-  where: { id: 'author-id' },
-  include: {
-    books: {
-      where: { published: true },
-      orderBy: { createdAt: 'desc' },
-      take: 5
-    }
-  }
-});
-```
-
-### Automatic Strategy Selection
-
-| Relation Type | Default Strategy | Reason |
-|--------------|------------------|--------|
-| `oneToOne` | `populate` | Simple relationships, no arrays |
-| `manyToOne` | `populate` | Single reference, no arrays |
-| `oneToMany` | `lookup` | Array of IDs in source document (e.g., Author.bookIds) |
-| `manyToMany` | `lookup` (if foreign key array specified) or `populate` (if join collection) | Foreign key arrays use server-side joins, join collections use separate queries |
-
-**Note:** The lookup strategy now supports include options (where, orderBy, take, skip) for both array foreign keys and single foreign key relations. However, nested includes are not yet supported for lookup strategy but are fully supported for populate strategy.
-
-**Many-to-Many Lookup Strategy:**
-
-When a many-to-many relationship uses foreign key arrays (either single-sided or both sides), Lenz automatically uses the `lookup` strategy with MongoDB's `$lookup` aggregation operator. This performs server-side joins for optimal read performance. For example, `post.categoryIds` array referencing categories.
-
-```graphql
-type Post @model {
-  categories: [Category!]! @relation(field: "categoryIds", strategy: "lookup")
-  categoryIds: [ID!]!  # multikey index automatically created
-}
-
-type Category @model {
-  posts: [Post!]! @relation(field: "postIds", strategy: "lookup", index: false)
-  postIds: [ID!]!  # no auto-index (index: false)
-}
-```
-
-**Many-to-Many Populate Strategy:**
-
-When a many-to-many relationship uses a join collection (no foreign key arrays), Lenz uses the `populate` strategy with separate queries.
-
-```graphql
-type Post @model {
-  categories: [Category!]! @relation  # no field parameter → join collection
-}
-
-type Category @model {
-  posts: [Post!]! @relation
-}
-```
-
-### Cascade Delete Behavior (`onDelete`)
-
-Lenz supports cascade delete operations on relations. By default, **no cascade is performed** (`onDelete: "NoAction"`) for performance and safety. You must explicitly opt in.
-
-| Value | Behavior |
-|-------|----------|
-| `NoAction` (default) | No cascade. Deleted document's related references become orphaned. |
-| `Cascade` | When a document is deleted, all related documents are also deleted. |
-| `SetNull` | When a document is deleted, foreign key fields in related documents are set to `null` (only for nullable FK fields). |
-
-**Important:** Cascade operations negatively impact write performance because each delete triggers additional queries. Use only when necessary.
-
-Examples:
-
-```graphql
-type Author @model {
-  id: ID! @id
-  posts: [Post!]! @relation(field: "postIds", onDelete: "Cascade")  # Deletes all posts when author is deleted
-  postIds: [ID!]!
-}
-
-type Profile @model {
-  id: ID! @id
-  user: User @relation(field: "userId", onDelete: "SetNull")  # Sets userId to null when user is deleted
-  userId: ID
-}
-```
-
-**Note:** `onDelete: "SetNull"` is only supported on nullable foreign key fields (optional `ID` fields, not `ID!`). Using it on required fields will cause a validation error.
-
-### Automatic Indexing
-
-Lenz automatically creates indexes for foreign key fields when `index: true` (default). You can disable this:
-
-```graphql
-type Author @model {
-  books: [Book!]! @relation(field: "bookIds", index: false)
-  bookIds: [ID!]!
-}
-```
-
-- For arrays (oneToMany): Creates multikey indexes
-- For single IDs (oneToOne, manyToOne): Creates sparse indexes
-
-## Supported Field Types
-
-- `String`
-- `Int`
-- `Float`
-- `Boolean`
-- `ID` (stored as String)
-- `DateTime` (JavaScript Date)
-- `Date` (JavaScript Date)
-- `Json` (any JSON value)
-- `ObjectId` (MongoDB ObjectId as string)
-
-## Best Practices with MongoDB
-
-### 1. Schema Design
-- **Embed documents** when data is accessed together frequently (use `@embedded` directive)
-- **Reference documents** when data is large or accessed independently
-- **Use arrays judiciously** - large arrays can impact performance
-- **Denormalize carefully** - duplicate data for read performance, but maintain consistency
-
-### 2. Index Strategy
-- **Auto-index foreign keys** - Lenz does this by default with `index: true`
-- **Add compound indexes** for frequently queried field combinations
-- **Use sparse indexes** for optional fields (auto-created for optional relations)
-- **Monitor index usage** with `$indexStats`
-
-### 3. Performance Optimization
-- **Use `lookup` strategy** for high-read bidirectional relationships
-- **Use `populate` strategy** for simple relationships and sharded clusters
-- **Batch operations** with `createMany`, `updateMany` instead of individual calls
-- **Project only needed fields** with `select` option
-
-### 4. Query Patterns
-- **Filter early** - push filters to database with `where` clauses
-- **Avoid large skip/limit** - use cursor-based pagination (`cursor` option)
-- **Use transactions** for multi-document consistency (requires replica set)
-- **Monitor slow queries** with MongoDB profiler
-
-### 5. Data Consistency
-- **Manual array sync** - when using `lookup` strategy, maintain ID arrays
-- **Use default values** for required fields to avoid validation errors
-- **Handle race conditions** with optimistic concurrency or transactions
-- **Implement soft deletes** with `deletedAt` field instead of hard deletes
-
-### 6. Many-to-Many Performance Optimization
-- **Array size limits:** Keep array sizes reasonable (<1000 elements). Large arrays increase `$lookup` complexity and memory usage.
-- **Batch synchronization:** When updating multiple relationships, batch array operations to reduce database round trips.
-- **Index management:** Regularly monitor and optimize multikey indexes for array fields.
-- **Alternative approaches:** For extremely large many-to-many relationships, consider:
-  - **Denormalization:** Embed frequently accessed data
-  - **Hybrid approach:** Use `lookup` for recent/active relationships, `populate` for historical
-  - **Materialized views:** Pre-compute relationships for read-heavy scenarios
-
-### 7. When to Use Each Strategy
-
-#### Use **Populate** when:
-- Simple one-to-one or many-to-one relationships
-- Working with sharded clusters (`$lookup` doesn't work across shards)
-- Relationships are rarely accessed
-- You prefer automatic data consistency
-- Many-to-many relationships with join collections (no foreign key arrays)
-- Small datasets where separate queries are acceptable
-
-#### Use **Lookup** when:
-- High-read scenarios with one-to-many or many-to-many relationships
-- Need server-side joins for complex filtering/sorting
-- Willing to manually maintain ID arrays
-- Maximum read performance is critical
-- Many-to-many relationships with foreign key arrays (both sides)
-- Medium to large datasets where join performance matters
-
-#### Special Considerations for Many-to-Many Lookup:
-- **Array size:** Large arrays (>1000 IDs) can impact `$lookup` performance. Consider denormalization or hybrid approaches.
-- **Indexing:** Multikey indexes are essential for array fields. Monitor index size and performance.
-- **Consistency:** Manual array synchronization requires careful application logic to maintain data integrity.
-- **Sharding:** `$lookup` doesn't work across shards. For sharded clusters, use `populate` strategy or ensure related documents are on the same shard.
-
-### 8. Production Readiness
-- **Enable replica set** for transaction support
-- **Set up proper connection pooling** in `lenz.config.ts`
-- **Implement retry logic** for transient failures
-- **Use environment-specific configurations**
-- **Monitor connection health** with regular `ping` commands
-
-## CLI Commands
-
-```bash
-# Initialize project
-npx lenz init
-
-# Generate ORM client
-npx lenz generate orm
-
-# Generate ORM client with custom config
-npx lenz generate orm --config lenz/lenz.config.ts
-
-# Generate Apollo Server CRUD modules
-npx lenz generate crud
-
-# Generate CRUD modules with custom paths
-npx lenz generate crud --schema lenz/schema.graphql --output ./src
-
-# Show help
-npx lenz --help
-
-# Show generate subcommands
-npx lenz generate
+})
 ```
 
-## Structure After Generation
+## Generated Structure
 
+### ORM-клиент (`lenz generate orm`)
 ```
-my-app/
-├── lenz/
-│   ├── schema.graphql          # Your GraphQL schema
-│   └── lenz.config.ts|js       # Configuration (TypeScript or JavaScript ESM)
-├── generated/
-│   └── lenz/
-│       └── client/             # Generated client
-│           ├── index.ts        # Main export
-│           ├── client.ts       # LenzClient class
-│           ├── types.ts        # TypeScript types
-│           ├── enums.ts        # Enum definitions
-│           ├── inputTypes.ts   # GraphQL input types (filters, CreateInput, UpdateInput)
-│           ├── runtime/        # Runtime utilities
-│           └── models/         # Model delegates
-└── .env                        # Environment variables
+generated/lenz/client/
+├── index.ts              # Экспорт LenzClient
+├── client.ts             # Класс LenzClient
+├── types.ts              # TypeScript типы
+├── enums.ts              # Enum-константы
+├── inputTypes.ts         # SDL input-типы (gql)
+├── models/
+│   ├── index.ts
+│   ├── User.ts           # UserDelegate (CRUD)
+│   └── Post.ts
+└── runtime/
+    ├── query.ts          # QueryBuilder
+    ├── pagination.ts     # PaginationHelper
+    ├── relations.ts      # RelationResolver
+    ├── errors.ts         # Runtime ошибки
+    └── logger.ts         # Logger
 ```
 
-### `lenz generate crud` — Apollo Server CRUD Modules
-
-Generates per-model Apollo Server modules (typeDefs + resolvers) from `lenz/schema.graphql`.
-
-**Опции:**
-- `-c, --config <path>` — путь к конфиг-файлу (по умолчанию: `lenz/lenz.config.ts`, с автоопределением `lenz/lenz.config.js`)
-- `-s, --schema <path>` — путь к схеме (по умолчанию: из конфига или `schema.graphql`)
-- `-o, --output <path>` — выходная директория (по умолчанию: из конфига `generate.crud.output` или `./src`)
-
-**Определение языка:** генератор определяет TypeScript или JavaScript по расширению конфиг-файла:
-- `lenz/lenz.config.ts` → генерирует `.ts` файлы
-- `lenz/lenz.config.js` → генерирует `.js` файлы
-
-Если конфиг не найден, по умолчанию используются `.ts` файлы.
-
-**Структура выхода:**
+### CRUD модули (`lenz generate crud`)
 ```
 src/
-├── index.ts                    # Баррель-файл: typeDefs + resolvers всех модулей
-├── Category/
+├── index.ts              # Баррель (typeDefs + resolvers)
+├── User/
 │   ├── typeDefs/
-│   │   ├── mutations.ts       # createCategory, updateCategory, deleteCategory
-│   │   └── queries.ts         # findUniqueCategory, findFirstCategory, findManyCategory, findManyCategoryCount
+│   │   ├── mutations.ts  # createUser, updateUser, deleteUser
+│   │   └── queries.ts    # findUnique, findFirst, findMany, findManyCount
 │   ├── resolvers/
-│   │   ├── mutations.ts       # Resolvers using { lenz } from context
+│   │   ├── mutations.ts  # { lenz } из контекста
 │   │   └── queries.ts
-│   └── index.ts               # Aggregated typeDefs and resolvers
-├── User/
-│   ├── ...
 │   └── index.ts
-└── ... (все модели)
+└── Post/...
 ```
 
-Баррель `src/index.ts` автоматически импортирует `inputTypes` из ORM-клиента и собирает все модули:
-
-```typescript
-// src/index.ts (сгенерировано)
-import { mergeTypeDefs, mergeResolvers } from '@graphql-tools/merge';
-import { inputTypes } from '../generated/lenz/client/inputTypes.js';
-import { categoryTypeDefs, categoryResolvers } from './Category/index.js';
-import { userTypeDefs, userResolvers } from './User/index.js';
-
-export const typeDefs = mergeTypeDefs([inputTypes, ...categoryTypeDefs, ...userTypeDefs]);
-export const resolvers = mergeResolvers([categoryResolvers, userResolvers]);
-```
-
-**Пример конфига (опционально):**
-```js
-// lenz/lenz.config.js
-export default {
-  schema: 'lenz/schema.graphql',
-  generate: {
-    crud: {
-      output: './src',
-    },
-  },
-};
-```
-
-**Использование с Apollo Server:**
-
-Резолверы получают экземпляр `LenzClient` через поле `lenz` GraphQL контекста — без импорта сервисов. Баррель `src/index.ts` уже собирает все typeDefs и resolvers:
-
-```typescript
-import { ApolloServer } from '@apollo/server';
-import { startStandaloneServer } from '@apollo/server/standalone';
-import { LenzClient } from '../generated/lenz/client/index.js';
-import { typeDefs, resolvers } from './src/index.js';
-
-const lenz = new LenzClient({ url: process.env.MONGO_URL });
-await lenz.$connect();
-
-const server = new ApolloServer({ typeDefs, resolvers });
-
-const { url } = await startStandaloneServer(server, {
-  context: async () => ({ lenz }),
-});
-```
-
-> **Важно:** `src/index.ts` автоматически импортирует `inputTypes` из ORM-клиента и объединяет их со всеми CRUD-модулями через `mergeTypeDefs` / `mergeResolvers`. Путь к ORM-клиенту берётся из конфига (`generate.client.output`) или используется `../generated/lenz/client` по умолчанию.
-
 ## Development
 
-### Build
-
-```bash
-npm run build
-```
-
-### Watch mode
-
-```bash
-npm run dev
-```
-
-### Lint
-
-```bash
-npm run lint
-```
-
-### Format
-
 ```bash
-npm run format
+npm run build        # tsc
+npm run dev          # tsc --watch
+npm test             # vitest
+npm run lint         # eslint
+npm run format       # prettier
 ```
 
 ## License
 
-MIT
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bairock/lenz",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "description": "Lenz ORM for MongoDB with GraphQL SDL - Prisma 7.0 style",
   "type": "module",
   "main": "dist/index.js",