flongo 2.1.0 → 2.2.0

package/README.md

@@ -168,6 +168,32 @@ const topRated = await products.aggregate([
 ]);
 ```
 
+#### Id projection & semi-joins (`getIds`)
+
+When you only need to know **which** documents match — not their contents —
+`getIds(query, pagination?)` returns matching `_id`s as strings. It uses a
+server-side projection, so full documents never leave the server. This is the
+natural fit for a semi-join: "of these N candidate ids, which pass this filter?"
+
+```typescript
+// Of these candidate stayIds, which are publicly visible?
+const visibleIds = await stays.getIds(
+  new FlongoQuery()
+    .where('_id').in(candidateStayIds)
+    .and('status').eq('Accepted')
+    .and('enable').eq(true)
+);
+```
+
+`getIds` honors the same query and pagination semantics as `getAll`, including
+sort clauses — ordered ids are useful for id-first pagination.
+
+> **Note (2.2.0):** inline `_id` clauses now compose with other field clauses,
+> as the example above relies on. Previously an `_id` clause caused every other
+> clause in the same clause list to be silently dropped, and filters had to be
+> attached via `.andQuery(new FlongoQuery().where('_id').in(ids))` — that
+> pattern still works unchanged.
+
 ### Collection Operations
 
 ```typescript
@@ -184,6 +210,7 @@ const user = await collection.create({
 // Read
 const user = await collection.get('user123');
 const users = await collection.getAll(query);
+const ids = await collection.getIds(query);   // matching _ids only (server-side projection)
 const first = await collection.getFirst(query);
 const count = await collection.count(query);
 const exists = await collection.exists(query);
@@ -502,6 +529,25 @@ const users = await collection.getAll(
 );
 ```
 
+## Changelog
+
+### 2.2.0
+
+- **`FlongoCollection.getIds(query?, pagination?)`** — returns matching `_id`s
+  as strings via a server-side projection (`{_id: 1}` on `find`, `$project` on
+  the aggregation path), so full documents never cross the wire. Honors the
+  same query, sort, and pagination semantics as `getAll`.
+- **Inline `_id` clauses now compose in `build()`.** Previously an `_id`
+  expression in the main clause list short-circuited the build and silently
+  discarded every other clause; combining `_id` with other filters required the
+  `.andQuery(new FlongoQuery().where('_id').in(ids))` workaround. Now `_id`
+  composes like any other field (string → ObjectId conversion is preserved for
+  both single values and `$in` arrays). Queries with **only** an `_id` clause
+  build identical output to before, and the `andQuery` pattern still works.
+  *Behavior note:* if a query combined `_id` with other clauses **and** relied
+  on those other clauses being ignored, it now returns only documents matching
+  all clauses — i.e., what the query literally says.
+
 ## License
 
 MIT

package/dist/flongoCollection.d.ts

@@ -98,6 +98,32 @@ export declare class FlongoCollection<T> {
      * @private
      */
     private getAllRandom;
+    /**
+     * Retrieves only the `_id`s of matching documents, as strings (the same
+     * normalization `toEntity` applies). Uses a server-side projection so full
+     * documents never leave the server — ideal for semi-joins ("which of these N
+     * ids match this filter?") and other membership checks where hydrating whole
+     * documents is wasted work.
+     *
+     * Honors the same query and pagination semantics as `getAll`, including sort
+     * clauses (ordered ids are useful for id-first pagination).
+     *
+     * Example usage:
+     * ```typescript
+     * // Semi-join: of these candidate stayIds, which are publicly visible?
+     * const visibleIds = await stays.getIds(
+     *   new FlongoQuery()
+     *     .where('_id').in(candidateStayIds)
+     *     .and('status').eq('Accepted')
+     *     .and('enable').eq(true)
+     * );
+     * ```
+     *
+     * @param query - Optional FlongoQuery for filtering
+     * @param pagination - Optional pagination settings
+     * @returns Promise resolving to the matching document ids as strings
+     */
+    getIds(query?: FlongoQuery, pagination?: Pagination): Promise<string[]>;
     /**
      * Runs a raw aggregation pipeline against this collection and returns the
      * documents with their `_id` normalized to a string (Entity form). A low-level

package/dist/flongoCollection.js

@@ -155,6 +155,49 @@ class FlongoCollection {
         const res = await this.collection.aggregate(pipeline).toArray();
         return res.map((d) => this.toEntity(d));
     }
+    /**
+     * Retrieves only the `_id`s of matching documents, as strings (the same
+     * normalization `toEntity` applies). Uses a server-side projection so full
+     * documents never leave the server — ideal for semi-joins ("which of these N
+     * ids match this filter?") and other membership checks where hydrating whole
+     * documents is wasted work.
+     *
+     * Honors the same query and pagination semantics as `getAll`, including sort
+     * clauses (ordered ids are useful for id-first pagination).
+     *
+     * Example usage:
+     * ```typescript
+     * // Semi-join: of these candidate stayIds, which are publicly visible?
+     * const visibleIds = await stays.getIds(
+     *   new FlongoQuery()
+     *     .where('_id').in(candidateStayIds)
+     *     .and('status').eq('Accepted')
+     *     .and('enable').eq(true)
+     * );
+     * ```
+     *
+     * @param query - Optional FlongoQuery for filtering
+     * @param pagination - Optional pagination settings
+     * @returns Promise resolving to the matching document ids as strings
+     */
+    async getIds(query, pagination) {
+        // Mirror getAll: a seeded random sort must execute via the aggregation
+        // pipeline. Only the id column is materialized on either path.
+        if (query?.hasRandomSort()) {
+            await this.assertRandomSortSupported();
+            const pipeline = query.buildPipeline(pagination);
+            pipeline.push({ $project: { _id: 1 } });
+            const res = await this.collection.aggregate(pipeline).toArray();
+            return res.map((d) => String(d._id));
+        }
+        const mongodbQuery = query?.build() ?? {};
+        const mongodbOptions = {
+            ...(query?.buildOptions(pagination) ?? new flongoQuery_1.FlongoQuery().buildOptions(pagination)),
+            projection: { _id: 1 }
+        };
+        const res = await this.collection.find(mongodbQuery, mongodbOptions).toArray();
+        return res.map((d) => String(d._id));
+    }
     /**
      * Runs a raw aggregation pipeline against this collection and returns the
      * documents with their `_id` normalized to a string (Entity form). A low-level

package/dist/flongoQuery.js

@@ -492,25 +492,24 @@ class FlongoQuery {
             // Process main expressions
             if (this.expressions) {
                 for (const expression of this.expressions) {
-                    // Special handling for _id field - convert strings to ObjectIds
+                    // Build query object for this clause
+                    let fieldValue;
                     if (expression.key === "_id") {
+                        // _id keeps its string -> ObjectId conversion but composes with the
+                        // other clauses like any field (it used to short-circuit the build,
+                        // silently discarding every co-existing clause).
                         if (Array.isArray(expression.val)) {
                             // Multiple IDs: {_id: {$in: [ObjectId(...), ObjectId(...)]}}
-                            mongodbQuery = {
-                                _id: {
-                                    [expression.op ?? "$in"]: expression.val.map((element) => new mongodb_1.ObjectId(element))
-                                }
+                            fieldValue = {
+                                [expression.op ?? "$in"]: expression.val.map((element) => new mongodb_1.ObjectId(element))
                             };
                         }
                         else {
                             // Single ID: {_id: ObjectId(...)}
-                            mongodbQuery = { _id: new mongodb_1.ObjectId(expression.val) };
+                            fieldValue = new mongodb_1.ObjectId(expression.val);
                         }
-                        break; // _id queries are typically exclusive
                     }
-                    // Build query object for non-_id fields
-                    let fieldValue;
-                    if (!expression.op) {
+                    else if (!expression.op) {
                         // Direct value assignment for simple equality (arrContains)
                         fieldValue = expression.val;
                     }
@@ -528,10 +527,14 @@ class FlongoQuery {
                         // Standard operator
                         fieldValue = { [expression.op]: expression.val };
                     }
-                    // Merge operators for the same field (e.g., range queries)
+                    // Merge operators for the same field (e.g., range queries).
+                    // ObjectId instances are direct values, not operator maps — spreading
+                    // one would destroy it, so they always assign.
                     if (mongodbQuery[expression.key] &&
                         typeof mongodbQuery[expression.key] === "object" &&
-                        typeof fieldValue === "object") {
+                        !(mongodbQuery[expression.key] instanceof mongodb_1.ObjectId) &&
+                        typeof fieldValue === "object" &&
+                        !(fieldValue instanceof mongodb_1.ObjectId)) {
                         mongodbQuery[expression.key] = { ...mongodbQuery[expression.key], ...fieldValue };
                     }
                     else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flongo",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Firestore-like fluent query API for MongoDB",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",