@atscript/mongo 0.1.26 → 0.1.28

package/skills/atscript-mongo/annotations.md

@@ -0,0 +1,168 @@
+# Annotations Reference — @atscript/mongo
+
+> All database and MongoDB-specific annotations available when using the mongo plugin.
+
+## Annotation Namespaces
+
+Annotations are split between core `@db.*` (database-generic) and `@db.mongo.*` (MongoDB-specific).
+
+## Core `@db.*` Annotations
+
+These come from `@atscript/core` and are used by the mongo plugin at runtime.
+
+### `@db.table "name"` (interface-level)
+
+Names the collection. **Required** for `AsCollection` to work.
+
+```atscript
+@db.table 'users'
+export interface User {
+    name: string
+}
+```
+
+### `@db.index.plain "name?", "sort?"` (field-level, multiple)
+
+Standard index. Fields sharing the same name form a compound index.
+
+```atscript
+@db.table 'products'
+export interface Product {
+    @db.index.plain 'cat_status'
+    category: string
+
+    @db.index.plain 'cat_status'
+    status: string
+}
+```
+
+### `@db.index.unique "name?"` (field-level, multiple)
+
+Unique constraint index.
+
+```atscript
+@db.table 'users'
+export interface User {
+    @db.index.unique 'email_idx'
+    email: string.email
+}
+```
+
+### `@db.index.fulltext "name?"` (field-level, multiple)
+
+Generic fulltext index (always weight 1 in MongoDB).
+
+```atscript
+@db.table 'articles'
+export interface Article {
+    @db.index.fulltext
+    title: string
+}
+```
+
+## MongoDB-Specific `@db.mongo.*` Annotations
+
+### `@db.mongo.collection` (interface-level, no args)
+
+Optional convenience annotation. When present, auto-injects `_id: mongo.objectId` if the interface doesn't define one. Validates that `_id` (if present) is not optional and is of type string, number, or mongo.objectId.
+
+```atscript
+@db.table 'users'
+@db.mongo.collection
+export interface User {
+    // _id: mongo.objectId — auto-injected
+    name: string
+}
+```
+
+### `@db.mongo.autoIndexes true|false` (interface-level)
+
+Toggle automatic index creation when `syncIndexes()` is called. Default: true.
+
+### `@db.mongo.index.text weight?` (field-level)
+
+MongoDB-specific text index with optional weight (number). Extends `@db.index.fulltext` with weight support.
+
+```atscript
+@db.table 'articles'
+export interface Article {
+    @db.mongo.index.text 10
+    title: string
+
+    @db.mongo.index.text 1
+    body: string
+}
+```
+
+### `@db.mongo.search.dynamic "analyzer?", fuzzy?` (interface-level)
+
+Dynamic Atlas Search index.
+
+### `@db.mongo.search.static "analyzer?", fuzzy?, "indexName?"` (interface-level, multiple)
+
+Named static Atlas Search index.
+
+### `@db.mongo.search.text "analyzer?", "indexName?"` (field-level, multiple)
+
+Atlas Search text field mapping.
+
+### `@db.mongo.search.vector dimensions, "similarity?", "indexName?"` (field-level)
+
+Vector search index. Similarity: `"cosine"`, `"euclidean"`, or `"dotProduct"`.
+
+```atscript
+@db.table 'documents'
+export interface Document {
+    @db.mongo.search.vector 1536, "cosine", "vector_idx"
+    embedding: mongo.vector
+}
+```
+
+### `@db.mongo.search.filter "indexName"` (field-level, multiple)
+
+Pre-filter field for vector search.
+
+### `@db.mongo.patch.strategy "replace"|"merge"` (field-level)
+
+Controls how nested objects and arrays are updated during patch operations. See [patches.md](patches.md) for details.
+
+### `@db.mongo.array.uniqueItems` (field-level)
+
+Enforces set-semantics on array `$insert` operations — duplicates are silently dropped.
+
+```atscript
+@db.table 'tags'
+export interface TaggedItem {
+    @db.mongo.array.uniqueItems
+    tags: string[]
+}
+```
+
+## Common Patterns
+
+### Full collection definition
+
+```atscript
+@db.table 'users'
+@db.mongo.collection
+export interface User {
+    @db.index.unique 'email_idx'
+    email: string.email
+
+    @db.mongo.index.text 5
+    @expect.minLength 2
+    name: string
+
+    @db.index.plain 'status_idx'
+    isActive: boolean
+
+    @db.mongo.patch.strategy 'merge'
+    profile: {
+        bio?: string
+        avatar?: string
+    }
+
+    @db.mongo.array.uniqueItems
+    tags?: string[]
+}
+```

package/skills/atscript-mongo/collections.md

@@ -0,0 +1,141 @@
+# Collections & CRUD — @atscript/mongo
+
+> Using AsMongo and AsCollection for database operations.
+
+## AsMongo
+
+Entry point for MongoDB operations. Wraps a `MongoClient` and provides a collection registry.
+
+```typescript
+import { AsMongo } from '@atscript/mongo'
+
+// From connection string
+const asMongo = new AsMongo('mongodb://localhost:27017/mydb')
+
+// From existing MongoClient
+const asMongo = new AsMongo(existingClient)
+
+// With logger
+const asMongo = new AsMongo(connectionString, myLogger)
+```
+
+### `getCollection<T>(type, logger?)`
+
+Returns an `AsCollection<T>` for the given Atscript annotated type. Collections are cached per type.
+
+```typescript
+import { User } from './user.as'
+
+const users = asMongo.getCollection(User)
+```
+
+## AsCollection
+
+Core collection abstraction providing validation, CRUD operations, and index management.
+
+### Properties
+
+- **`name`** — Collection name (from `@db.table`)
+- **`collection`** — Raw MongoDB `Collection` instance
+- **`flatMap`** — `Map<string, TAtscriptAnnotatedType>` of all fields in dot-notation
+
+### Insert
+
+```typescript
+// Insert one
+const result = await users.insert({
+  email: 'alice@example.com',
+  name: 'Alice',
+  isActive: true,
+})
+
+// Insert many
+const result = await users.insert([
+  { email: 'alice@example.com', name: 'Alice', isActive: true },
+  { email: 'bob@example.com', name: 'Bob', isActive: false },
+])
+```
+
+Validates the payload before inserting. Auto-generates `ObjectId` for `_id` if type is `mongo.objectId`.
+
+### Replace
+
+```typescript
+await users.replace({
+  _id: '507f1f77bcf86cd799439011',
+  email: 'alice@new.com',
+  name: 'Alice Updated',
+  isActive: true,
+})
+```
+
+Validates the full document and replaces by `_id`.
+
+### Update (Patch)
+
+```typescript
+await users.update({
+  _id: '507f1f77bcf86cd799439011',
+  name: 'New Name',
+  // Only updates specified fields
+})
+```
+
+Uses `CollectionPatcher` internally to build MongoDB aggregation pipelines. See [patches.md](patches.md) for array patch operations.
+
+### Validation
+
+```typescript
+// Get a validator for different contexts
+const insertValidator = users.getValidator('insert')
+const updateValidator = users.getValidator('update')
+const patchValidator = users.getValidator('patch')
+
+// Create a custom validator
+const validator = users.createValidator({
+  partial: true,
+  plugins: [myPlugin],
+  skipList: new Set(['internalField']),
+})
+```
+
+### Index Management
+
+```typescript
+// Sync indexes — creates/drops to match .as definitions
+await users.syncIndexes()
+```
+
+Only manages indexes prefixed with `atscript__`. User-created indexes are not touched.
+
+Reads index definitions from:
+- `@db.index.plain` → standard indexes
+- `@db.index.unique` → unique indexes
+- `@db.index.fulltext` → text indexes (weight 1)
+- `@db.mongo.index.text` → text indexes (custom weight)
+- `@db.mongo.search.*` → Atlas Search indexes
+
+### Querying
+
+```typescript
+// Find documents
+const cursor = users.collection.find({ isActive: true })
+
+// Use the raw MongoDB collection for queries
+const doc = await users.collection.findOne({ _id: users.prepareId(id) })
+```
+
+### `prepareId(id)`
+
+Converts a string ID to `ObjectId` if the collection uses `mongo.objectId` type for `_id`.
+
+```typescript
+const objectId = users.prepareId('507f1f77bcf86cd799439011')
+```
+
+## Best Practices
+
+- Use `getValidator()` for context-specific validation before custom operations
+- Call `syncIndexes()` on application startup to ensure indexes match definitions
+- Use `prepareId()` when working with raw MongoDB queries to handle ObjectId conversion
+- The `flatMap` property is lazily built — first access triggers computation

package/skills/atscript-mongo/core.md

@@ -0,0 +1,83 @@
+# Core Setup — @atscript/mongo
+
+> Plugin installation, configuration, and architecture overview.
+
+## Installation
+
+```bash
+npm install @atscript/mongo
+# peer dependencies:
+npm install @atscript/core @atscript/typescript mongodb
+```
+
+## Plugin Configuration
+
+Add `MongoPlugin()` to your `atscript.config.ts`:
+
+```typescript
+import { defineConfig } from '@atscript/core'
+import { ts } from '@atscript/typescript'
+import { MongoPlugin } from '@atscript/mongo'
+
+export default defineConfig({
+  rootDir: 'src',
+  plugins: [ts(), MongoPlugin()],
+})
+```
+
+The plugin registers:
+- **Primitives**: `mongo.objectId` (24-char hex string), `mongo.vector` (number array)
+- **Annotations**: All `@db.mongo.*` annotations (collection, indexes, search, patch, array)
+
+## Architecture
+
+```
+@atscript/mongo
+├── plugin/
+│   ├── index.ts          — MongoPlugin factory
+│   ├── annotations.ts    — All db.mongo.* annotation specs
+│   └── primitives.ts     — mongo.objectId, mongo.vector
+└── lib/
+    ├── as-mongo.ts        — AsMongo: MongoDB client wrapper
+    ├── as-collection.ts   — AsCollection: collection abstraction (validation, indexes, CRUD)
+    ├── collection-patcher.ts — Converts patch payloads to MongoDB aggregation pipelines
+    └── validate-plugins.ts   — Validator plugins for ObjectId and unique arrays
+```
+
+## Primitives
+
+### `mongo.objectId`
+
+A string type constrained to `/^[a-fA-F0-9]{24}$/`. Used for MongoDB `_id` fields.
+
+```atscript
+export interface User {
+    _id: mongo.objectId
+    name: string
+}
+```
+
+### `mongo.vector`
+
+An alias for `number[]`. Used for vector search fields.
+
+```atscript
+export interface Document {
+    embedding: mongo.vector
+}
+```
+
+## Regenerating atscript.d.ts
+
+After annotation changes, regenerate the type declarations:
+
+```bash
+cd packages/mongo && node ../typescript/dist/cli.cjs -f dts
+```
+
+## Best Practices
+
+- Always use `@db.table` to name your collections — it's required by `AsCollection`
+- `@db.mongo.collection` is optional — it only auto-injects `_id: mongo.objectId` if missing
+- Use `mongo.objectId` type for `_id` fields when you want ObjectId-based IDs
+- Use `string` type for `_id` when you want string-based IDs

package/skills/atscript-mongo/patches.md

@@ -0,0 +1,205 @@
+# Patch Strategies — @atscript/mongo
+
+> How `@db.mongo.patch.strategy` and array patch operations work.
+
+## Overview
+
+When updating documents via `AsCollection.update()`, the `CollectionPatcher` converts your patch payload into MongoDB aggregation pipeline stages. The behavior depends on two things:
+
+1. **`@db.mongo.patch.strategy`** on objects — controls whether nested objects are replaced or merged
+2. **Array key fields** (`@expect.array.key`) and patch operations — controls how array elements are matched and modified
+
+## Object Patch Strategies
+
+### Default (no annotation) — Replace
+
+Without `@db.mongo.patch.strategy`, nested objects are fully replaced:
+
+```atscript
+@db.table 'users'
+export interface User {
+    address: {
+        line1: string
+        city: string
+        zip: string
+    }
+}
+```
+
+```typescript
+// This replaces the entire address object
+await users.update({
+  _id: id,
+  address: { line1: '123 Main St', city: 'NYC', zip: '10001' },
+})
+```
+
+### `@db.mongo.patch.strategy 'replace'`
+
+Explicit replacement — same as default. The entire nested object is overwritten.
+
+### `@db.mongo.patch.strategy 'merge'`
+
+Individual fields within the nested object are updated without affecting unspecified fields:
+
+```atscript
+@db.table 'users'
+export interface User {
+    @db.mongo.patch.strategy 'merge'
+    contacts: {
+        email: string
+        phone: string
+    }
+}
+```
+
+```typescript
+// Only updates phone, email is preserved
+await users.update({
+  _id: id,
+  contacts: { phone: '+1-555-0100' },
+})
+```
+
+### Nested strategies
+
+Strategies can be applied at any nesting level:
+
+```atscript
+@db.table 'config'
+export interface Config {
+    @db.mongo.patch.strategy 'merge'
+    settings: {
+        @db.mongo.patch.strategy 'replace'
+        theme: { primary: string, secondary: string }
+
+        @db.mongo.patch.strategy 'merge'
+        notifications: { email: boolean, push: boolean }
+    }
+}
+```
+
+## Array Patch Operations
+
+Top-level arrays in a patch payload use a structured format with operation keys.
+
+### `$replace`
+
+Replaces the entire array:
+
+```typescript
+await collection.update({
+  _id: id,
+  tags: { $replace: ['new', 'tags', 'only'] },
+})
+```
+
+### `$insert`
+
+Appends items to the array:
+
+```typescript
+await collection.update({
+  _id: id,
+  tags: { $insert: ['newTag1', 'newTag2'] },
+})
+```
+
+If `@db.mongo.array.uniqueItems` is set, duplicates are silently dropped (uses `$setUnion`).
+
+### `$upsert`
+
+Insert-or-update by key. For keyed arrays (`@expect.array.key`), removes existing elements matching the key(s) and appends the new ones:
+
+```atscript
+@db.table 'products'
+export interface Product {
+    items: {
+        @expect.array.key
+        sku: string
+        quantity: number
+        price: number
+    }[]
+}
+```
+
+```typescript
+await products.update({
+  _id: id,
+  items: {
+    $upsert: [
+      { sku: 'ABC', quantity: 10, price: 9.99 },  // replaces existing ABC or inserts
+    ],
+  },
+})
+```
+
+For non-keyed arrays, behaves like `$addToSet` (deep equality).
+
+### `$update`
+
+Updates existing array elements matched by key:
+
+```typescript
+await products.update({
+  _id: id,
+  items: {
+    $update: [
+      { sku: 'ABC', quantity: 20 },  // updates only quantity for sku=ABC
+    ],
+  },
+})
+```
+
+With `@db.mongo.patch.strategy 'merge'` on the array field, uses `$mergeObjects` to merge into the matched element. Without it, replaces the matched element entirely.
+
+### `$remove`
+
+Removes array elements:
+
+```typescript
+// Keyed — removes by key match
+await products.update({
+  _id: id,
+  items: {
+    $remove: [{ sku: 'ABC' }],
+  },
+})
+
+// Non-keyed — removes by deep equality
+await collection.update({
+  _id: id,
+  tags: {
+    $remove: ['obsoleteTag'],
+  },
+})
+```
+
+## Array Keys
+
+Use `@expect.array.key` to mark fields that uniquely identify array elements:
+
+```atscript
+export interface Translations {
+    entries: {
+        @expect.array.key
+        lang: string
+        @expect.array.key
+        key: string
+        value: string
+    }[]
+}
+```
+
+Multiple key fields form a composite key — elements are matched when ALL key fields match.
+
+## Implementation Details
+
+The `CollectionPatcher` converts patch payloads into MongoDB aggregation pipeline stages using:
+- `$reduce` + `$filter` + `$concatArrays` for keyed upsert/remove
+- `$map` + `$cond` + `$mergeObjects` for keyed update with merge
+- `$setUnion` for unique/non-keyed insert
+- `$setDifference` for non-keyed remove
+- `$concatArrays` for plain append
+
+All operations are performed atomically in a single `updateOne()` call using an aggregation pipeline.