@lossless.org/nosqldb 10.5.0 → 10.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lossless.org/nosqldb",
-  "version": "10.5.0",
+  "version": "10.6.0",
   "private": false,
   "description": "A MongoDB-compatible embedded database server with wire protocol support, backed by a high-performance Rust engine.",
   "exports": {
@@ -14,12 +14,12 @@
   "devDependencies": {
     "@api.global/typedserver": "^8.4.6",
     "@design.estate/dees-element": "^2.2.4",
-    "@git.zone/tsbuild": "^4.5.0",
-    "@git.zone/tsbundle": "^2.13.0",
-    "@git.zone/tsrust": "^1.13.2",
-    "@git.zone/tstest": "^6.1.1",
+    "@git.zone/tsbuild": "^5.0.0",
+    "@git.zone/tsbundle": "^2.15.0",
+    "@git.zone/tsrust": "^1.15.1",
+    "@git.zone/tstest": "^6.2.1",
     "@lossless.org/client": "0.1.1",
-    "@types/node": "26.5.1",
+    "@types/node": "26.6.1",
     "mongodb": "^7.5.0"
   },
   "dependencies": {

package/readme.md

@@ -559,6 +559,17 @@ see the transaction snapshot plus its staged changes. Commit validates conflicts
 and publishes atomically; abort discards staged changes. Write conflicts report
 `WriteConflict` (112) with `TransientTransactionError`.
 
+A staged write conflicts when it touches a document `_id` or a unique index key
+that another transaction or statement wrote after this transaction's snapshot:
+for example two transactions that both read a claim as absent and then insert
+it under the same `_id`, or under distinct `_id`s with the same unique key.
+Statements validate against the snapshot, so such a collision is reported when
+the loser commits; nothing of the losing transaction is published. The driver's
+`withTransaction` retries the transient error, and the retry observes the
+winner. A key already visible in the transaction's snapshot is not a conflict:
+inserting it fails the statement with `DuplicateKey` (11000), as outside a
+transaction.
+
 Commit/abort outcomes and successful retryable statement results survive file
 storage restart. Duplicate commits replay their outcome; abort after commit
 reports `TransactionCommitted` (256), commit after abort reports
@@ -1298,7 +1309,7 @@ await collection.findOneAndReplace({ _id: id }, { name: 'Replaced' }, { returnDo
 
 // Element
 { email: { $exists: true } }
-{ type: { $type: 'string' } }
+{ type: { $type: 'string' } }       { value: { $type: ['int', 'long'] } }
 
 // Array
 { tags: { $all: ['mongodb', 'database'] } }
@@ -1307,8 +1318,28 @@ await collection.findOneAndReplace({ _id: id }, { name: 'Replaced' }, { returnDo
 
 // Regex
 { name: { $regex: /^Al/i } }
+
+// Aggregation expressions
+{ owner: 'o', $expr: { $lte: [{ $add: ['$retainedBytes', '$reservedBytes', size] }, max] } }
+{ $expr: { $gt: ['$leaseExpiresAt', '$$NOW'] } }
 ```
 
+`$type` takes a type alias (`'string'`, `'number'`, …), a numeric BSON type
+code or an array of them, and matches an array field through its elements as
+well as `'array'` itself.
+
+`$expr` evaluates an aggregation expression per document in `find`, `count`,
+`distinct`, `update`, `delete`, `findAndModify` and a `$match` stage, and
+matches when the result is truthy. It accepts the operators listed under
+[Aggregation Pipeline](#aggregation-pipeline). Evaluation is charged against
+the same work budget as every other predicate, and an operator the engine does
+not implement is refused by name with `TypeMismatch` (code 14) before any
+document is read. `$$NOW` is one instant per command, as in MongoDB: the
+engine reads the clock once when the command starts, and the command's filter,
+every document of a pipeline update, every aggregation stage, `$lookup` and
+`$unionWith` sub-pipeline, and every `getMore` of its cursor see that instant.
+Filters outside a command, such as a partial index filter, have no `$$NOW`.
+
 ### Update Operators
 
 ```typescript
@@ -1345,15 +1376,57 @@ const results = await collection.aggregate([
 
 **Supported stages:** `$match`, `$project`, `$group`, `$sort`, `$limit`, `$skip`, `$unwind`, `$lookup`, `$addFields`, `$count`, `$facet`, `$replaceRoot`, `$set`, `$unionWith`, `$out`, `$merge`
 
-**Supported expression operators:** `$eq`, `$and`, `$literal`, `$map`,
-`$objectToArray`, `$setEquals`, plus `$field` paths, `$$variable` references
-including `$$ROOT`, and documents or arrays of those. Every other operator is
-refused by name with `TypeMismatch` (code 14) before any document is read; the
-engine never treats an operator it cannot execute as a literal value.
+**Supported expression operators:**
+
+| Group | Operators |
+| --- | --- |
+| Comparison | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$cmp` |
+| Arithmetic | `$add`, `$subtract`, `$multiply`, `$divide` |
+| Logical | `$and`, `$or`, `$not` |
+| Conditional and variables | `$cond` (array or `if`/`then`/`else` form), `$ifNull` (two or more operands), `$let` |
+| Type and arrays | `$isNumber`, `$type`, `$in`, `$size`, `$arrayElemAt` |
+| Dates | `$dateAdd` |
+| Collections | `$map`, `$objectToArray`, `$setEquals` |
+| Literals | `$literal` |
+
+plus `$field` paths, `$$variable` references including `$$ROOT` and `$$NOW`,
+and documents or arrays of those. Every other operator is refused by name with
+`TypeMismatch` (code 14) before any document is read; the engine never treats
+an operator it cannot execute as a literal value.
+
+Expressions follow MongoDB's value semantics. A field that is absent is
+*missing*, which is not `null`: `$type` answers `'missing'`, `$ifNull`
+replaces both, and comparisons order values as MongoDB does (MinKey, missing,
+`null`, numbers, strings, objects, arrays, binary data, ObjectIds, booleans,
+dates, timestamps, regular expressions, MaxKey), so `{ $eq: ['$absent', null] }`
+is false. Numbers compare by value across their wire types. A path through an
+array maps over its elements and always answers an array: `'$mailbox.path'`
+over one looked-up document is `['INBOX']`, so `$arrayElemAt` and `$size`
+apply to it. Arithmetic answers `null` when an operand is `null` or missing;
+an int result that overflows widens to a long and a long to a double, a double
+operand makes the result a double, and `$divide` always answers a double.
+`$add` accepts one date and answers a date; date minus date is milliseconds.
+Runtime errors keep MongoDB 7's codes: a non-numeric operand is
+`TypeMismatch` (14), `can't $divide by zero` is `BadValue` (2), a date that
+leaves the 64-bit range is `Overflow` (15), and the array and date operators
+answer MongoDB's location codes (a second date in `$add` 16612, `$in` without
+an array 40081, `$size` without an array 17124, `$arrayElemAt` 28689–28691,
+`$dateAdd` 5166403, 5166405, 5166406 and 5439013, a non-string time zone
+40517, an unknown unit `FailedToParse` (9)). Decimal128 operands in arithmetic
+are refused with `TypeMismatch` (14) — decimal arithmetic is not
+implemented. `$and`, `$or`, `$cond` and `$ifNull`
+evaluate, and charge, only the operands MongoDB evaluates, so a guard keeps an
+invalid branch from failing the statement. `$dateAdd` computes in UTC with the
+units `millisecond` to `year`, clamping `month`, `quarter` and `year` to the
+end of the target month; a `timezone` other than UTC is refused by name.
+Within a document expression a member that is missing is still written as
+`null`, where MongoDB omits the member.
 
 `$lookup` supports the equality form and a bounded correlated pipeline form with
-`let`, an optional `$match` using `$expr`/`$and`/`$eq`, and an optional following
-`$limit`. Correlated string equality predicates can use a full-key or subset
+`let`, an optional `$match` (any filter, `$expr` included), and an optional
+following `$limit`. A `let` variable that reads an absent local field is bound
+to the missing value, as in MongoDB. Correlated string equality predicates
+(`$expr` with `$eq`, optionally under `$and`) can use a full-key or subset
 foreign equality index to reduce candidates when available. Candidates are
 paged, the complete expression remains authoritative, and `$limit` counts only
 exact expression matches. Other BSON value shapes use the bounded scan path.
@@ -1368,6 +1441,18 @@ matcher cannot pre-compile fall back to the unnarrowed load, so results are
 unchanged. The materialization limit therefore applies to the matched set, which
 is what lets `countDocuments(filter)` run against collections larger than it.
 
+The scalar members of a `$in` or `$nin` list are looked up in a set built when
+the filter is validated, so a document costs the size of its value, not the
+length of the list: `countDocuments({ _id: { $in: ids } })` answers for tens of
+thousands of ids. Equality is unchanged: numbers of every type are equal by
+value (1, `NumberLong(1)`, 1.0 and `NumberDecimal("1.00")`), an array field
+matches through its elements or as a whole, and a missing field matches a list
+that holds `null`. Documents, arrays and regular expressions in a list are
+compared one by one and charged as such. A regular expression in a list is
+still compared as a value and not yet applied to strings, which differs from
+MongoDB, where it matches the strings it describes; that difference is a known
+open defect.
+
 **Group accumulators:** `$sum`, `$avg`, `$min`, `$max`, `$first`, `$last`, `$push`, `$addToSet`, `$count`
 
 `$group._id` accepts a literal (`null`, a number, a string), a `$field`
@@ -1397,12 +1482,50 @@ await collection.dropIndexes();  // drop all except _id
 > 🛡️ **Unique indexes are enforced at the engine level.** Duplicate values are rejected with a `DuplicateKey` error (code 11000) *before* the document is written to disk — on `insertOne`, `updateOne`, `findAndModify`, and upserts. Index definitions and entries are committed with native storage and survive restart.
 
 NoSQLDB supports ascending and descending index keys with `name`, `unique`,
-`sparse`, and `expireAfterSeconds` options. It accepts `background` as a
-validated no-op and index version `v: 2`. Unsupported options, including
-`partialFilterExpression`, `collation`, and `hidden`, are rejected before any
-index in the request is created. Native maintenance expires eligible BSON dates
-and date arrays in bounded batches, preserving publication holds and active
-snapshots.
+`sparse`, `partialFilterExpression` and `expireAfterSeconds` options. It
+accepts `background` as a validated no-op and index version `v: 2`.
+Unsupported options, including `collation` and `hidden`, are rejected before
+any index in the request is created. Native maintenance expires eligible BSON
+dates and date arrays in bounded batches, preserving publication holds and
+active snapshots.
+
+**Partial indexes.** An index with a `partialFilterExpression` holds only the
+documents that match the filter, and a unique partial index enforces
+uniqueness among those documents only:
+
+```typescript
+await jobs.createIndex(
+  { activeClaimKey: 1 },
+  { unique: true, partialFilterExpression: { activeClaimKey: { $exists: true } } },
+);
+await pulls.createIndex(
+  { org: 1, repo: 1, sourceRef: 1, targetRef: 1 },
+  { unique: true, partialFilterExpression: { state: 'open' } },
+);
+```
+
+The filter accepts MongoDB's subset: equality (`field: value` or `$eq`),
+`$exists: true`, `$gt`, `$gte`, `$lt`, `$lte`, `$type`, `$in`, `$and` and
+`$or`, nested at most four expression levels deep. Any other expression —
+`$exists: false`, `$ne`, `$nin`, `$not`, `$nor`, regular expressions,
+`$elemMatch`, `$size`, `$expr`, and a regular expression inside `$in` — and a
+filter combined with `sparse` are refused with `CannotCreateIndex` (code 67);
+a malformed filter is `BadValue` (2) and a non-document is `TypeMismatch` (14).
+An update that moves a document into the filter claims its key, one that moves
+it out releases it, and transactions claim keys the same way, so a racing
+claim is a `WriteConflict` (112) with `TransientTransactionError`.
+`listIndexes`, canonical export and import report the filter exactly as it was
+created. The filter identifies the index: the same name with a different
+filter is `IndexKeySpecsConflict` (86); the same key with an equivalent filter
+under another name is `IndexOptionsConflict` (85); a different filter over the
+same key under another name is a separate index. Equivalence treats implicit
+equality and `$eq`, the order of conjuncts and `$or` branches, numeric wire
+types and `$in` duplicates as MongoDB's normalised expressions do. The query
+planner never selects a partial index on its own; a `hint` naming one reads
+only its members, as MongoDB's hinted scan does. A partial TTL index expires
+only its members. Engines older than this release refuse a storage root that
+holds a partial index instead of enforcing its uniqueness over every
+document.
 
 `find()` and collection `aggregate()` accept `hint` as an index name (including
 `_id_`) or an exact ascending/descending key pattern. Key-pattern order matters;

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@lossless.org/nosqldb',
-  version: '10.5.0',
+  version: '10.6.0',
   description: 'A MongoDB-compatible embedded database server with wire protocol support, backed by a high-performance Rust engine.'
 }