@atscript/db-mongo 0.1.39 → 0.1.40

package/skills/atscript-db-mongo/collections.md

@@ -7,16 +7,16 @@
 Entry point for MongoDB operations. Wraps a `MongoClient` and provides a collection registry.
 
 ```typescript
-import { AsMongo } from '@atscript/db-mongo'
+import { AsMongo } from "@atscript/db-mongo";
 
 // From connection string
-const asMongo = new AsMongo('mongodb://localhost:27017/mydb')
+const asMongo = new AsMongo("mongodb://localhost:27017/mydb");
 
 // From existing MongoClient
-const asMongo = new AsMongo(existingClient)
+const asMongo = new AsMongo(existingClient);
 
 // With logger
-const asMongo = new AsMongo(connectionString, myLogger)
+const asMongo = new AsMongo(connectionString, myLogger);
 ```
 
 ### `getCollection<T>(type, logger?)`
@@ -24,9 +24,9 @@ const asMongo = new AsMongo(connectionString, myLogger)
 Returns an `AsCollection<T>` for the given Atscript annotated type. Collections are cached per type.
 
 ```typescript
-import { User } from './user.as'
+import { User } from "./user.as";
 
-const users = asMongo.getCollection(User)
+const users = asMongo.getCollection(User);
 ```
 
 ## AsCollection
@@ -44,16 +44,16 @@ Core collection abstraction providing validation, CRUD operations, and index man
 ```typescript
 // Insert one
 const result = await users.insert({
-  email: 'alice@example.com',
-  name: 'Alice',
+  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 },
-])
+  { 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`.
@@ -62,11 +62,11 @@ Validates the payload before inserting. Auto-generates `ObjectId` for `_id` if t
 
 ```typescript
 await users.replace({
-  _id: '507f1f77bcf86cd799439011',
-  email: 'alice@new.com',
-  name: 'Alice Updated',
+  _id: "507f1f77bcf86cd799439011",
+  email: "alice@new.com",
+  name: "Alice Updated",
   isActive: true,
-})
+});
 ```
 
 Validates the full document and replaces by `_id`.
@@ -75,10 +75,10 @@ Validates the full document and replaces by `_id`.
 
 ```typescript
 await users.update({
-  _id: '507f1f77bcf86cd799439011',
-  name: 'New Name',
+  _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.
@@ -87,28 +87,29 @@ Uses `CollectionPatcher` internally to build MongoDB aggregation pipelines. See
 
 ```typescript
 // Get a validator for different contexts
-const insertValidator = users.getValidator('insert')
-const updateValidator = users.getValidator('update')
-const patchValidator = users.getValidator('patch')
+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']),
-})
+  skipList: new Set(["internalField"]),
+});
 ```
 
 ### Index Management
 
 ```typescript
 // Sync indexes — creates/drops to match .as definitions
-await users.syncIndexes()
+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)
@@ -119,10 +120,10 @@ Reads index definitions from:
 
 ```typescript
 // Find documents
-const cursor = users.collection.find({ isActive: true })
+const cursor = users.collection.find({ isActive: true });
 
 // Use the raw MongoDB collection for queries
-const doc = await users.collection.findOne({ _id: users.prepareId(id) })
+const doc = await users.collection.findOne({ _id: users.prepareId(id) });
 ```
 
 ### `prepareId(id)`
@@ -130,7 +131,7 @@ const doc = await users.collection.findOne({ _id: users.prepareId(id) })
 Converts a string ID to `ObjectId` if the collection uses `mongo.objectId` type for `_id`.
 
 ```typescript
-const objectId = users.prepareId('507f1f77bcf86cd799439011')
+const objectId = users.prepareId("507f1f77bcf86cd799439011");
 ```
 
 ## Best Practices

package/skills/atscript-db-mongo/core.md

@@ -15,17 +15,18 @@ npm install @atscript/core @atscript/typescript mongodb
 Add `MongoPlugin()` to your `atscript.config.ts`:
 
 ```typescript
-import { defineConfig } from '@atscript/core'
-import { ts } from '@atscript/typescript'
-import MongoPlugin from '@atscript/db-mongo/plugin'
+import { defineConfig } from "@atscript/core";
+import { ts } from "@atscript/typescript";
+import MongoPlugin from "@atscript/db-mongo/plugin";
 
 export default defineConfig({
-  rootDir: 'src',
+  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)
 

package/skills/atscript-db-mongo/patches.md

@@ -30,8 +30,8 @@ export interface User {
 // This replaces the entire address object
 await users.update({
   _id: id,
-  address: { line1: '123 Main St', city: 'NYC', zip: '10001' },
-})
+  address: { line1: "123 Main St", city: "NYC", zip: "10001" },
+});
 ```
 
 ### `@db.mongo.patch.strategy 'replace'`
@@ -57,8 +57,8 @@ export interface User {
 // Only updates phone, email is preserved
 await users.update({
   _id: id,
-  contacts: { phone: '+1-555-0100' },
-})
+  contacts: { phone: "+1-555-0100" },
+});
 ```
 
 ### Nested strategies
@@ -90,8 +90,8 @@ Replaces the entire array:
 ```typescript
 await collection.update({
   _id: id,
-  tags: { $replace: ['new', 'tags', 'only'] },
-})
+  tags: { $replace: ["new", "tags", "only"] },
+});
 ```
 
 ### `$insert`
@@ -101,8 +101,8 @@ Appends items to the array:
 ```typescript
 await collection.update({
   _id: id,
-  tags: { $insert: ['newTag1', 'newTag2'] },
-})
+  tags: { $insert: ["newTag1", "newTag2"] },
+});
 ```
 
 If `@db.mongo.array.uniqueItems` is set, duplicates are silently dropped (uses `$setUnion`).
@@ -128,10 +128,10 @@ await products.update({
   _id: id,
   items: {
     $upsert: [
-      { sku: 'ABC', quantity: 10, price: 9.99 },  // replaces existing ABC or inserts
+      { sku: "ABC", quantity: 10, price: 9.99 }, // replaces existing ABC or inserts
     ],
   },
-})
+});
 ```
 
 For non-keyed arrays, behaves like `$addToSet` (deep equality).
@@ -145,10 +145,10 @@ await products.update({
   _id: id,
   items: {
     $update: [
-      { sku: 'ABC', quantity: 20 },  // updates only quantity for sku=ABC
+      { 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.
@@ -162,17 +162,17 @@ Removes array elements:
 await products.update({
   _id: id,
   items: {
-    $remove: [{ sku: 'ABC' }],
+    $remove: [{ sku: "ABC" }],
   },
-})
+});
 
 // Non-keyed — removes by deep equality
 await collection.update({
   _id: id,
   tags: {
-    $remove: ['obsoleteTag'],
+    $remove: ["obsoleteTag"],
   },
-})
+});
 ```
 
 ## Array Keys
@@ -196,6 +196,7 @@ Multiple key fields form a composite key — elements are matched when ALL key f
 ## 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

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025-present Artem Maltsev
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/dist/agg-CUX5Jb_A.mjs

@@ -1,75 +0,0 @@
-import { buildMongoFilter } from "./mongo-filter-CL69Yhcm.mjs";
-import { resolveAlias } from "@atscript/db/agg";
-
-//#region packages/db-mongo/src/agg.ts
-/** Simple accumulators that map directly to `{ $<fn>: '$field' }`. */ const SIMPLE_ACCUMULATORS = {
-	sum: "$sum",
-	avg: "$avg",
-	min: "$min",
-	max: "$max"
-};
-/**
-* Maps an AggregateExpr to a MongoDB $group accumulator expression.
-*/ function toAccumulator(expr) {
-	const simple = SIMPLE_ACCUMULATORS[expr.$fn];
-	if (simple) return { [simple]: `$${expr.$field}` };
-	if (expr.$fn === "count") {
-		if (expr.$field === "*") return { $sum: 1 };
-		return { $sum: { $cond: [
-			{ $ne: [`$${expr.$field}`, null] },
-			1,
-			0
-		] } };
-	}
-	throw new Error(`Unsupported aggregate function: ${expr.$fn}`);
-}
-/**
-* Builds the common prefix stages: $match + $group._id from groupBy fields.
-* Shared by both full aggregate and count pipelines.
-*/ function buildPrefix(query) {
-	const controls = query.controls || {};
-	const groupBy = controls.$groupBy ?? [];
-	const pipeline = [{ $match: buildMongoFilter(query.filter) }];
-	const groupId = {};
-	for (const field of groupBy) groupId[field] = `$${field}`;
-	return {
-		pipeline,
-		groupId,
-		groupBy,
-		controls
-	};
-}
-function buildAggregatePipeline(query) {
-	const { pipeline, groupId, groupBy, controls } = buildPrefix(query);
-	const groupStage = { _id: groupId };
-	const project = { _id: 0 };
-	const aggregates = controls.$select?.aggregates;
-	for (const field of groupBy) project[field] = `$_id.${field}`;
-	if (aggregates) for (const expr of aggregates) {
-		const alias = resolveAlias(expr);
-		groupStage[alias] = toAccumulator(expr);
-		project[alias] = 1;
-	}
-	pipeline.push({ $group: groupStage });
-	pipeline.push({ $project: project });
-	if (controls.$having) pipeline.push({ $match: buildMongoFilter(controls.$having) });
-	if (controls.$sort) pipeline.push({ $sort: controls.$sort });
-	if (controls.$skip) pipeline.push({ $skip: controls.$skip });
-	if (controls.$limit) pipeline.push({ $limit: controls.$limit });
-	return pipeline;
-}
-function buildCountPipeline(query) {
-	const { pipeline, groupId, groupBy, controls } = buildPrefix(query);
-	pipeline.push({ $group: { _id: groupId } });
-	if (controls.$having) {
-		const project = { _id: 0 };
-		for (const field of groupBy) project[field] = `$_id.${field}`;
-		pipeline.push({ $project: project });
-		pipeline.push({ $match: buildMongoFilter(controls.$having) });
-	}
-	pipeline.push({ $count: "count" });
-	return pipeline;
-}
-
-//#endregion
-export { buildAggregatePipeline, buildCountPipeline };

package/dist/agg-FBVtOv9k.cjs

@@ -1,77 +0,0 @@
-"use strict";
-const require_mongo_filter = require('./mongo-filter-C8w5by9H.cjs');
-const __atscript_db_agg = require_mongo_filter.__toESM(require("@atscript/db/agg"));
-
-//#region packages/db-mongo/src/agg.ts
-/** Simple accumulators that map directly to `{ $<fn>: '$field' }`. */ const SIMPLE_ACCUMULATORS = {
-	sum: "$sum",
-	avg: "$avg",
-	min: "$min",
-	max: "$max"
-};
-/**
-* Maps an AggregateExpr to a MongoDB $group accumulator expression.
-*/ function toAccumulator(expr) {
-	const simple = SIMPLE_ACCUMULATORS[expr.$fn];
-	if (simple) return { [simple]: `$${expr.$field}` };
-	if (expr.$fn === "count") {
-		if (expr.$field === "*") return { $sum: 1 };
-		return { $sum: { $cond: [
-			{ $ne: [`$${expr.$field}`, null] },
-			1,
-			0
-		] } };
-	}
-	throw new Error(`Unsupported aggregate function: ${expr.$fn}`);
-}
-/**
-* Builds the common prefix stages: $match + $group._id from groupBy fields.
-* Shared by both full aggregate and count pipelines.
-*/ function buildPrefix(query) {
-	const controls = query.controls || {};
-	const groupBy = controls.$groupBy ?? [];
-	const pipeline = [{ $match: require_mongo_filter.buildMongoFilter(query.filter) }];
-	const groupId = {};
-	for (const field of groupBy) groupId[field] = `$${field}`;
-	return {
-		pipeline,
-		groupId,
-		groupBy,
-		controls
-	};
-}
-function buildAggregatePipeline(query) {
-	const { pipeline, groupId, groupBy, controls } = buildPrefix(query);
-	const groupStage = { _id: groupId };
-	const project = { _id: 0 };
-	const aggregates = controls.$select?.aggregates;
-	for (const field of groupBy) project[field] = `$_id.${field}`;
-	if (aggregates) for (const expr of aggregates) {
-		const alias = (0, __atscript_db_agg.resolveAlias)(expr);
-		groupStage[alias] = toAccumulator(expr);
-		project[alias] = 1;
-	}
-	pipeline.push({ $group: groupStage });
-	pipeline.push({ $project: project });
-	if (controls.$having) pipeline.push({ $match: require_mongo_filter.buildMongoFilter(controls.$having) });
-	if (controls.$sort) pipeline.push({ $sort: controls.$sort });
-	if (controls.$skip) pipeline.push({ $skip: controls.$skip });
-	if (controls.$limit) pipeline.push({ $limit: controls.$limit });
-	return pipeline;
-}
-function buildCountPipeline(query) {
-	const { pipeline, groupId, groupBy, controls } = buildPrefix(query);
-	pipeline.push({ $group: { _id: groupId } });
-	if (controls.$having) {
-		const project = { _id: 0 };
-		for (const field of groupBy) project[field] = `$_id.${field}`;
-		pipeline.push({ $project: project });
-		pipeline.push({ $match: require_mongo_filter.buildMongoFilter(controls.$having) });
-	}
-	pipeline.push({ $count: "count" });
-	return pipeline;
-}
-
-//#endregion
-exports.buildAggregatePipeline = buildAggregatePipeline
-exports.buildCountPipeline = buildCountPipeline