@adobe-commerce/aio-toolkit 1.2.1 → 1.2.2

package/CHANGELOG.md

@@ -5,6 +5,99 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.2] - 2026-04-01
+
+### 🐛 Bug Fixes
+
+- **fix(abdb): Fixed `AbdbRepository` update path — `_updated_at` was placed outside `$set`**
+
+  `save(payload, id)` delegated to `updateOne` with `{ $set: payload }` as the payload, but `updateOne` then spread that into `{ $set: payload, _updated_at: now }`. The `_updated_at` key landed at the top level alongside `$set`, making it an invalid MongoDB update document. The `$set` wrapping is now done inside `updateOne` and `update`, so timestamps are always nested correctly.
+
+- **fix(abdb): Fixed `update` method passing an array to `updateMany`**
+
+  `update` (previously `updateAll`) accepted `Array<Partial<T>> | Partial<T>` and always converted the input to an array before passing it as the second argument to `updateMany`. MongoDB's `updateMany` expects a **single** update document, not an array — this caused silent failures at runtime. The method now accepts a single `Partial<T>` and wraps it in `{ $set: ... }`.
+
+- **fix(abdb): Fixed full schema validation on partial update payloads**
+
+  `updateOne` and `update` were calling `this._collection.validate()` (full validation — all required fields must be present) on update payloads. This caused spurious validation errors when patching a subset of fields. Both methods now use `_validatePartial`, which only checks the columns present in the payload.
+
+### ✨ Features
+
+- **feat(abdb): Expanded `AbdbRepository` API with granular single- and bulk-operation methods**
+
+  Five new public methods covering the full MongoDB CRUD surface:
+
+  | New method | Description |
+  |---|---|
+  | `findById(id)` | Shorthand for `findOne({ _id: new ObjectId(id) })` |
+  | `insertOne(payload)` | Single-document insert via `insertOne`; stamps timestamps and validates |
+  | `updateOne(payload, filter?, options?)` | Single-document update via `updateOne` with `$set` wrapping and partial validation |
+  | `deleteOne(filter?)` | Single-document delete via `deleteOne`; returns raw result |
+  | `deleteById(id)` | Shorthand for `deleteOne({ _id: new ObjectId(id) })` |
+
+- **feat(abdb): `save` delegates to `insertOne` / `updateOne`** — eliminates duplicated timestamp-stamping and validation logic.
+
+- **feat(abdb): Split `exists` into `isIdExists` and `exists(filter, options?)`**
+
+  The original `exists(id: string)` only supported lookup by `_id`. It has been renamed to `isIdExists(id)` (preserving the empty-id guard that returns `false` without hitting the DB), and a new general-purpose `exists(filter?, options?)` method has been added that accepts any filter and proxies to `count`.
+
+- **feat(abdb): `count` now accepts an optional `options` parameter**
+
+  `count(filter?, options?)` now forwards `options` to the underlying `countDocuments` call, enabling fine-grained control such as `{ limit: 1 }` for fast existence probes.
+
+### ⚠️ Breaking Changes
+
+- **`exists(id: string)` renamed to `isIdExists(id: string)`**
+
+  `exists` now accepts a general-purpose filter object. Any caller using `repo.exists(someId)` must switch to `repo.isIdExists(someId)`.
+
+- **`delete(id: string)` → `delete(filter: AbdbRepositoryFilter)`**
+
+  `delete` previously accepted a string `_id` and silently no-oped when the id was empty. It now accepts a filter object and uses `deleteMany` under the hood (consistent with `deleteAll`). Use `deleteById(id)` for the old single-by-id behaviour.
+
+- **`insertAll` renamed to `insert`** — identical behaviour, new name aligns with `insertOne`.
+
+- **`updateAll` renamed to `update`** — identical behaviour (plus bug fixes above), new name aligns with `updateOne`.
+
+- **Return types of all mutation methods changed to `Promise<Record<string, any>>`**
+
+  `save`, `insert`, `insertOne`, `update`, `updateOne`, `delete`, `deleteOne`, `deleteById`, and `deleteAll` previously returned `Promise<string>`, `Promise<string[]>`, `Promise<number>`, or `Promise<void>`. All now return the raw MongoDB result document so callers have access to `acknowledged`, `insertedId`, `insertedIds`, `modifiedCount`, `deletedCount`, etc.
+
+### 💡 Migration Guide
+
+```typescript
+// existence check by id — OLD
+const found = await repo.exists(id);
+// existence check by id — NEW
+const found = await repo.isIdExists(id);
+
+// general existence check (new) — by any filter
+const active = await repo.exists({ status: 'active' });
+
+// delete by id — OLD
+await repo.delete(id);
+// delete by id — NEW
+await repo.deleteById(id);
+
+// bulk insert — OLD
+const ids = await repo.insertAll([...]);
+// bulk insert — NEW
+const result = await repo.insert([...]);  // result.insertedIds contains the ids
+
+// bulk update — OLD
+await repo.updateAll({ active: false }, { email: 'bob@example.com' });
+// bulk update — NEW
+await repo.update({ active: false }, { email: 'bob@example.com' });
+
+// return value of save (insert path) — OLD: string _id
+const id = await repo.save({ name: 'Jane', email: 'jane@example.com' });
+// return value of save (insert path) — NEW: raw insertOne result
+const result = await repo.save({ name: 'Jane', email: 'jane@example.com' });
+// result.insertedId contains the new _id
+```
+
+---
+
 ## [1.2.1] - 2026-03-31
 
 ### ✨ Features

package/README.md

@@ -848,7 +848,7 @@ A generic CRUD repository that wraps an `AbdbCollection` and holds the IMS token
 ##### Basic usage
 
 ```javascript
-const { AbdbRepository, AbdbColumnType } = require('@adobe-commerce/aio-toolkit');
+const { AbdbRepository } = require('@adobe-commerce/aio-toolkit');
 const { generateAccessToken } = require('@adobe/aio-sdk').Core.AuthClient;
 const UserCollection = require('@lib/UserCollection');
 
@@ -858,11 +858,12 @@ exports.main = async (params) => {
 
   const repo = new AbdbRepository(new UserCollection(), accessToken);
 
-  // Insert — returns the new document _id
-  const id = await repo.save({ first_name: 'Jane', last_name: 'Doe', email: 'jane@example.com' });
+  // Insert — returns raw insertOne result (result.insertedId contains the new _id)
+  const insertResult = await repo.save({ first_name: 'Jane', last_name: 'Doe', email: 'jane@example.com' });
+  const id = insertResult.insertedId;
 
-  // Read one by _id
-  const doc = await repo.findOne({ _id: id });
+  // Read by _id (shorthand)
+  const doc = await repo.findById(id);
 
   // Read one by any field
   const byEmail = await repo.findOne({ email: 'jane@example.com' });
@@ -874,8 +875,8 @@ exports.main = async (params) => {
   // Partial update — only provided fields are validated; required fields already in the DB are not re-checked
   await repo.save({ first_name: 'Janet' }, id);
 
-  // Delete
-  await repo.delete(id);
+  // Delete by _id
+  await repo.deleteById(id);
 };
 ```
 
@@ -896,21 +897,26 @@ These are added once per collection instance, so re-using the same collection ac
 
 | Method | Description | Returns |
 |---|---|---|
-| `save(payload)` | Insert a new document (full validation) | `Promise<string>` — new `_id` |
-| `save(payload, id)` | Partial update by `_id` (only present fields validated) | `Promise<string>` — same `id` |
-| `findOne(filter)` | First document matching filter, e.g. `{ _id: 'x' }` | `Promise<T \| null>` |
+| `save(payload)` | Insert via `insertOne` (full validation, stamps both timestamps) | `Promise<Record<string, any>>` — raw `insertOne` result |
+| `save(payload, id)` | Update via `updateOne` with `upsert: true` (partial validation, stamps `_updated_at`) | `Promise<Record<string, any>>` — raw `updateOne` result |
+| `insertOne(payload)` | Single-document insert (full validation, stamps both timestamps) | `Promise<Record<string, any>>` — raw `insertOne` result (e.g. `insertedId`) |
+| `updateOne(payload, filter?, options?)` | Single-document update via `{ $set: payload }` (partial validation, stamps `_updated_at`) | `Promise<Record<string, any>>` — raw `updateOne` result (e.g. `modifiedCount`) |
+| `findOne(filter)` | First document matching filter, e.g. `{ email: 'a@b.com' }` | `Promise<T \| null>` |
+| `findById(id)` | Shorthand for `findOne({ _id: new ObjectId(id) })` | `Promise<T \| null>` |
 | `find(filter?)` | All documents matching filter (default: all) | `Promise<T[]>` |
-| `exists(id)` | Lightweight existence check via `countDocuments` | `Promise<boolean>` |
-| `delete(id)` | Delete document by `_id`; no-ops for empty id | `Promise<void>` |
-| `count(filter?)` | Count matching documents (default: all) | `Promise<number>` |
+| `isIdExists(id)` | Returns `true` if a document with the given `_id` exists (no-op for empty id) | `Promise<boolean>` |
+| `exists(filter?, options?)` | Returns `true` if any document matching `filter` exists via `countDocuments` | `Promise<boolean>` |
+| `deleteOne(filter?)` | Delete first matching document via `deleteOne` | `Promise<Record<string, any>>` — raw `deleteOne` result |
+| `deleteById(id)` | Shorthand for `deleteOne({ _id: new ObjectId(id) })` | `Promise<Record<string, any>>` |
+| `count(filter?, options?)` | Count matching documents via `countDocuments` (default: all) | `Promise<number>` |
 
 **Bulk operations (single DB round-trip each):**
 
 | Method | Description | Returns |
 |---|---|---|
-| `insertAll(payloads[])` | Bulk insert via `insertMany` — each payload stamped and validated | `Promise<string[]>` — inserted ids |
-| `updateAll(payload, filter?)` | Bulk partial update via `updateMany` — stamps `_updated_at` | `Promise<void>` |
-| `deleteAll(filter?)` | Bulk delete via `deleteMany` (default: all documents) | `Promise<void>` |
+| `insert(payloads[])` | Bulk insert via `insertMany` — each payload stamped and validated | `Promise<Record<string, any>>` — raw `insertMany` result (e.g. `insertedIds`) |
+| `update(payload, filter?, options?)` | Bulk update via `updateMany` with `{ $set: payload }` — stamps `_updated_at`, partial validation | `Promise<Record<string, any>>` — raw `updateMany` result (e.g. `modifiedCount`) |
+| `delete(filter?)` | Bulk delete via `deleteMany` (default: all documents) | `Promise<Record<string, any>>` — raw `deleteMany` result (e.g. `deletedCount`) |
 
 **Accessors:**
 
@@ -930,19 +936,22 @@ const repo = new AbdbRepository(new UserCollection(), accessToken, 'emea');
 
 ```javascript
 // Insert multiple documents in one DB call
-const ids = await repo.insertAll([
+const result = await repo.insert([
   { first_name: 'Alice', last_name: 'Smith', email: 'alice@example.com' },
   { first_name: 'Bob',   last_name: 'Jones', email: 'bob@example.com'   },
 ]);
+console.log(result.insertedIds); // array of inserted _id values
 
 // Update all matching documents in one DB call
-await repo.updateAll({ active: false }, { email: 'bob@example.com' });
+const updateResult = await repo.update({ active: false }, { email: 'bob@example.com' });
+console.log(updateResult.modifiedCount); // number of documents updated
 
 // Delete all matching documents in one DB call
-await repo.deleteAll({ active: false });
+const deleteResult = await repo.delete({ active: false });
+console.log(deleteResult.deletedCount); // number of documents deleted
 
 // Delete everything in the collection
-await repo.deleteAll();
+await repo.delete();
 ```
 
 ### 🏪 Commerce Components  

package/dist/index.d.mts

@@ -281,13 +281,18 @@ declare class AbdbRepository<T extends AbdbRecord = AbdbRecord> {
     getCollection(): AbdbCollection;
     find(filter?: AbdbRepositoryFilter): Promise<T[]>;
     findOne(filter: AbdbRepositoryFilter): Promise<T | null>;
-    exists(id: string): Promise<boolean>;
-    count(filter?: AbdbRepositoryFilter): Promise<number>;
-    save(payload?: Partial<T>, id?: string): Promise<string>;
-    delete(id?: string): Promise<void>;
-    insertAll(payloads: Array<Partial<T>>): Promise<string[]>;
-    updateAll(payload: Partial<T>, filter?: AbdbRepositoryFilter): Promise<void>;
-    deleteAll(filter?: AbdbRepositoryFilter): Promise<void>;
+    findById(id: string): Promise<T | null>;
+    delete(filter?: AbdbRepositoryFilter): Promise<Record<string, any>>;
+    deleteOne(filter?: AbdbRepositoryFilter): Promise<Record<string, any>>;
+    deleteById(id: string): Promise<Record<string, any>>;
+    insert(payloads: Array<Partial<T>>): Promise<Record<string, any>>;
+    insertOne(payload: Partial<T>): Promise<Record<string, any>>;
+    update(payload: Partial<T>, filter?: AbdbRepositoryFilter, options?: Record<string, any>): Promise<Record<string, any>>;
+    updateOne(payload: Partial<T>, filter?: AbdbRepositoryFilter, options?: Record<string, any>): Promise<Record<string, any>>;
+    save(payload?: Partial<T>, id?: string): Promise<Record<string, any>>;
+    isIdExists(id: string): Promise<boolean>;
+    exists(filter?: AbdbRepositoryFilter, options?: Record<string, any>): Promise<boolean>;
+    count(filter?: AbdbRepositoryFilter, options?: Record<string, any>): Promise<number>;
     private _validatePartial;
 }
 

package/dist/index.d.ts

@@ -281,13 +281,18 @@ declare class AbdbRepository<T extends AbdbRecord = AbdbRecord> {
     getCollection(): AbdbCollection;
     find(filter?: AbdbRepositoryFilter): Promise<T[]>;
     findOne(filter: AbdbRepositoryFilter): Promise<T | null>;
-    exists(id: string): Promise<boolean>;
-    count(filter?: AbdbRepositoryFilter): Promise<number>;
-    save(payload?: Partial<T>, id?: string): Promise<string>;
-    delete(id?: string): Promise<void>;
-    insertAll(payloads: Array<Partial<T>>): Promise<string[]>;
-    updateAll(payload: Partial<T>, filter?: AbdbRepositoryFilter): Promise<void>;
-    deleteAll(filter?: AbdbRepositoryFilter): Promise<void>;
+    findById(id: string): Promise<T | null>;
+    delete(filter?: AbdbRepositoryFilter): Promise<Record<string, any>>;
+    deleteOne(filter?: AbdbRepositoryFilter): Promise<Record<string, any>>;
+    deleteById(id: string): Promise<Record<string, any>>;
+    insert(payloads: Array<Partial<T>>): Promise<Record<string, any>>;
+    insertOne(payload: Partial<T>): Promise<Record<string, any>>;
+    update(payload: Partial<T>, filter?: AbdbRepositoryFilter, options?: Record<string, any>): Promise<Record<string, any>>;
+    updateOne(payload: Partial<T>, filter?: AbdbRepositoryFilter, options?: Record<string, any>): Promise<Record<string, any>>;
+    save(payload?: Partial<T>, id?: string): Promise<Record<string, any>>;
+    isIdExists(id: string): Promise<boolean>;
+    exists(filter?: AbdbRepositoryFilter, options?: Record<string, any>): Promise<boolean>;
+    count(filter?: AbdbRepositoryFilter, options?: Record<string, any>): Promise<number>;
     private _validatePartial;
 }