typeferry 0.11.0 → 0.13.0

package/dist/minimongo/README.md

@@ -0,0 +1,329 @@
+# TypeFerry local collections
+
+`typeferry/minimongo` is TypeFerry's browser-safe, framework-neutral local
+document store. The import path is stable package history; the behavior is
+defined only by TypeFerry's types, tests, and documentation.
+
+It provides immutable documents, Mongo-style selectors and modifiers, and
+typed events without importing TypeFerry transports, React, or the MongoDB
+driver.
+
+```ts
+import { LocalCollection } from 'typeferry/minimongo'
+
+interface Task {
+  title: string
+  priority: number
+  details: {
+    done: boolean
+  }
+}
+
+const tasks = new LocalCollection<Task>('tasks')
+const id = tasks.insert({
+  title: 'Ship local collections',
+  priority: 1,
+  details: { done: false },
+})
+
+tasks.update(id, { $set: { 'details.done': true } })
+
+const urgent = tasks.find(
+  { priority: { $lte: 2 } },
+  { sort: { priority: 1 } },
+)
+
+console.log(urgent.fetch())
+```
+
+## IDs and immutable documents
+
+Every document has a lowercase, 24-character hexadecimal string `_id`. This is
+the client representation TypeFerry uses for the default MongoDB ObjectId
+identity. `insert()` generates an ID when none is supplied and rejects IDs in
+other formats. The local package does not import the MongoDB driver.
+
+Inserted values are cloned before storage. Materialized documents and event
+payloads are deeply readonly and frozen. Unchanged documents retain their
+identity across query snapshots, which makes reference comparison useful in UI
+and state-management code.
+
+```ts
+const before = urgent.fetch()
+
+tasks.insert({
+  title: 'Unrelated task',
+  priority: 10,
+  details: { done: false },
+})
+
+const after = urgent.fetch()
+
+console.log(before[0] === after[0]) // true
+```
+
+## Collection events
+
+Collections follow TypeFerry's `on`, `off`, `once`, `onAny`, and `offAny`
+event-emitter conventions. Events contain immutable snapshots.
+
+```ts
+tasks.on('insert', ({ document }) => {
+  console.log('inserted', document._id)
+})
+
+tasks.on('update', ({ previous, document }) => {
+  console.log('changed', previous, document)
+})
+
+tasks.on('remove', ({ document }) => {
+  console.log('removed', document._id)
+})
+```
+
+Collection events are emitted before dependent cursors publish their updated
+results.
+
+## Cursor events
+
+A cursor starts observing its collection when its first event listener is
+added. It stops automatically after all listeners are removed, or explicitly
+with `cursor.stop()`.
+
+```ts
+urgent.on('added', ({ document, index }) => {
+  console.log('entered query', document, index)
+})
+
+urgent.on('changed', ({ previous, document, previousIndex, index }) => {
+  console.log('changed inside query', previous, document, previousIndex, index)
+})
+
+urgent.on('removed', ({ document, index }) => {
+  console.log('left query', document, index)
+})
+
+urgent.on('change', documents => {
+  console.log('complete result snapshot', documents)
+})
+```
+
+Granular events describe rows entering, changing within, or leaving the result.
+The `change` event follows them once with the complete result snapshot. A
+mutation that does not affect the query result emits nothing from that cursor.
+
+## API reference
+
+### `LocalCollection<TSchema>`
+
+Create a collection with an optional diagnostic name:
+
+```ts
+const tasks = new LocalCollection<Task>('tasks')
+```
+
+`TSchema` describes insertable application fields. Materialized documents add
+a readonly string `_id` and recursively make schema fields readonly.
+
+| Member | Result | Behavior |
+|---|---|---|
+| `name` | `string \| undefined` | The name supplied to the constructor. It does not create persistence or a global registry. |
+| `insert(document)` | `string` | Clones, validates, freezes, and inserts one document. Generates `_id` when omitted. Emits `insert`. |
+| `insertAsync(document)` | `Promise<string>` | Async convenience form of `insert`; the mutation and event happen synchronously before the promise settles. |
+| `find(selector?, options?)` | `Cursor` | Creates a lazy cursor. Calling `find()` with no arguments selects all documents. |
+| `findOne(selector?, options?)` | document or `undefined` | Returns the first matching result after options are applied. Calling `findOne()` with no arguments selects all documents. |
+| `findOneAsync(selector?, options?)` | `Promise<document \| undefined>` | Async convenience form of `findOne`. |
+| `countDocuments(selector?, options?)` | `Promise<number>` | Counts matching documents after `skip` and `limit`. |
+| `estimatedDocumentCount(options?)` | `Promise<number>` | Counts all documents after `skip` and `limit`; no estimate or index is involved. |
+| `update(selector, modifier, options?)` | `number` | Updates the first match, or every match with `{ multi: true }`. Emits one `update` per document. |
+| `updateAsync(...)` | `Promise<number>` | Async convenience form of `update`. |
+| `upsert(selector, modifier, options?)` | `UpsertResult` | Updates matching documents or inserts one derived document. `insertedId` can supply the ID for the insert branch. |
+| `upsertAsync(...)` | `Promise<UpsertResult>` | Async convenience form of `upsert`. |
+| `remove(selector)` | `number` | Removes every match and emits one `remove` per document. |
+| `removeAsync(selector)` | `Promise<number>` | Async convenience form of `remove`. |
+| `on`, `once`, `off` | collection | Adds or removes a typed listener and supports chaining. Duplicate registration of the same listener is ignored. |
+| `onAny`, `offAny` | collection | Adds or removes a listener receiving `(eventName, payload)`. |
+| `removeAllListeners(event?)` | collection | Removes listeners for one event or for the entire collection. |
+
+`documents()` and `addObserver()` are exposed to satisfy the cursor contract.
+They are low-level integration members: application queries should use
+`find()`, and application observation should use typed collection or cursor
+events. `documents()` returns the current stored snapshots in insertion order.
+`addObserver(callback)` returns an unsubscribe function and supplies only an
+invalidation signal.
+
+### Collection events
+
+| Event | Payload |
+|---|---|
+| `insert` | `{ document }` containing the inserted snapshot. |
+| `update` | `{ previous, document }` containing the snapshots before and after the update. |
+| `remove` | `{ document }` containing the removed snapshot. |
+
+For a multi-document mutation, collection events follow collection iteration
+order. Collection events run synchronously after state changes and before
+dependent cursor events. A listener exception propagates to the mutating
+caller; it does not roll back the completed state change.
+
+### `Cursor<TDocument, TOutput>`
+
+Obtain cursors from `LocalCollection.find()`. Constructing a cursor directly is
+not an application API because its collection contract contains package-owned
+runtime state.
+
+| Member | Result | Behavior |
+|---|---|---|
+| `matcher` | `Matcher<TDocument>` | Compiled matcher used by this cursor. |
+| `count()` | `number` | Counts the current result after `skip` and `limit`. |
+| `countAsync()` | `Promise<number>` | Async convenience form of `count`. |
+| `fetch()` | readonly document array | Evaluates and freezes the current result. |
+| `fetchAsync()` | promise of readonly document array | Async convenience form of `fetch`. |
+| `forEach(callback, thisArg?)` | `void` | Iterates one evaluated snapshot in result order. |
+| `forEachAsync(callback, thisArg?)` | `Promise<void>` | Awaits each callback sequentially in result order. |
+| `map(callback, thisArg?)` | array | Maps one evaluated snapshot. |
+| `mapAsync(callback, thisArg?)` | `Promise<array>` | Awaits each mapping callback sequentially. |
+| `getTransform()` | transform or `undefined` | Returns the identity-preserving transform configured through `FindOptions`. |
+| `stop()` | `void` | Detaches collection observation and clears the saved result. Existing listeners remain registered. Adding another listener starts observation again. |
+| `[Symbol.iterator]()` | iterator | Iterates the result of one `fetch()`. |
+| `[Symbol.asyncIterator]()` | async iterator | Asynchronously iterates the result of one `fetch()`. |
+| `on`, `once`, `off` | cursor | Manages typed cursor listeners and supports chaining. |
+| `onAny`, `offAny` | cursor | Manages listeners receiving `(eventName, payload)`. |
+| `removeAllListeners(event?)` | cursor | Removes listeners; removing the last listener automatically stops observation. |
+
+Adding the first listener captures the current result as the baseline. Initial
+rows are not emitted as `added`; events describe subsequent mutations.
+
+### Cursor events
+
+| Event | Payload |
+|---|---|
+| `added` | `{ document, index }` when a document enters the result. |
+| `changed` | `{ previous, document, previousIndex, index }` when a result document's visible value changes. |
+| `removed` | `{ document, index }` when a document leaves the result. |
+| `change` | The complete readonly result array, emitted once after granular events. |
+
+An ordering-only change emits `change` without inventing a row-level change.
+Projection and transform output determine whether a cursor-visible document
+changed. Every payload and snapshot is frozen.
+
+### Selectors
+
+A selector is either a string document ID or a typed object. Object fields use
+dot-separated paths and may contain literal values or operators.
+
+| Group | Supported syntax |
+|---|---|
+| Comparison | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin` |
+| Presence and negation | `$exists`, `$not` |
+| Logical | `$and`, `$or`, `$nor`; `$comment` is accepted and does not affect matching |
+| Strings | `RegExp`, `$regex`, `$options`; supported flags are `i`, `m`, and `g` |
+| Arrays | Literal element matching, `$all`, `$elemMatch`, `$size` |
+| Numbers and binary | `$mod`, `$bitsAllClear`, `$bitsAllSet`, `$bitsAnyClear`, `$bitsAnySet` |
+| Value type | `$type` with supported BSON-style aliases or numeric codes |
+| Location | `$near`, optional `$maxDistance`, coordinate pairs, and GeoJSON `Point` values |
+
+`$near` uses Euclidean distance for coordinate pairs and meters for GeoJSON
+points. It also supplies the default nearest-first ordering when no explicit
+sort is provided. JavaScript predicates and `$where` are not supported.
+
+### Find options
+
+| Option | Type | Behavior |
+|---|---|---|
+| `sort` | object, tuple array, field array, or comparator | Orders results. Directions are `1`, `-1`, `asc`, `desc`, `ascending`, or `descending`. |
+| `skip` | `number` | Omits results from the beginning of the ordered result. Defaults to `0`. |
+| `limit` | `number` | Caps the returned result after `skip`. |
+| `projection` | field map | Includes or excludes fields using `1`/`true` or `0`/`false`. Inclusion and exclusion cannot be mixed except for `_id`. |
+| `transform` | function or `null` | Maps every projected document while retaining its original `_id`. It must return an object and cannot replace `_id`. |
+| `collation` | `CollationOptions` | Applies `Intl.Collator` string comparison using the required `locale` and supported strength, case, and numeric options. |
+
+Sorting accepts nested paths. Sorting across parallel arrays is rejected.
+Projection operators such as `$slice`, `$elemMatch`, and `$meta` are not
+supported inside the projection document.
+
+### Mutations
+
+An update can be a replacement document or an operator document, but cannot mix
+the two forms. `_id` is immutable. Dot paths are typed from the collection
+schema, and positional `.$.` updates use array-match metadata from the selector.
+
+| Operator | Behavior |
+|---|---|
+| `$set`, `$unset`, `$rename` | Writes, removes, or renames fields. |
+| `$inc`, `$mul`, `$min`, `$max` | Applies numeric changes or bounds. |
+| `$currentDate` | Stores the current `Date`; accepts `true` or `{ $type: 'date' }`. |
+| `$push` | Appends an item or uses `$each`, `$position`, `$slice`, and `$sort`. |
+| `$pushAll` | Appends an array of items. |
+| `$addToSet` | Adds distinct items; accepts one value or `$each`. |
+| `$pop` | Removes from the beginning for a negative argument or the end otherwise. |
+| `$pull`, `$pullAll` | Removes array elements matching a value selector or value list. |
+| `$setOnInsert` | Applies only when `upsert()` takes its insert branch. |
+
+`UpdateOptions` contains `multi?: boolean`. `UpsertOptions` contains
+`multi?: boolean` and `insertedId?: string`. `UpsertResult` always contains
+`numberAffected`; `insertedId` is present only when an insert occurred.
+
+### `Matcher` and `Sorter`
+
+These are exported for advanced query tooling:
+
+```ts
+const matcher = new Matcher<Task>({ priority: { $lte: 2 } })
+const matches = matcher.documentMatches(task)
+
+const compare = new Sorter<Task>({ priority: 1 }).getComparator()
+```
+
+`Matcher.documentMatches()` returns `MatchResult` with `result` and optional
+geospatial `distance` or positional `arrayIndices`. `hasGeoQuery()` identifies
+a `$near` selector, and `isSimple()` reports whether compilation found only
+simple field matching. `isIdSelector(value)` narrows any string to the ID
+selector type. It identifies selector syntax; collection mutations separately
+validate the required lowercase, 24-character hexadecimal ID format.
+
+`Sorter.getComparator({ distances? })` returns a comparator. The optional
+distance map supports nearest-first sorting for geospatial queries. `_getPaths()`
+on both helpers exposes their compiled field paths for package tooling; the
+underscore marks it as a low-level API.
+
+### Errors
+
+`LocalQueryError` reports invalid selectors, collation, and sort input.
+`LocalCollectionError` reports duplicate IDs, invalid projections, and invalid
+mutations. It includes optional `field` and `setPropertyError` context when the
+failure is tied to a mutation path. Invalid ID formats and cyclic document
+values raise `TypeError`.
+
+### Exported types
+
+The entrypoint exports the following type families:
+
+- Documents: `MinimongoId`, `InsertDocument`, `MaterializedDocument`,
+  `TransformedDocument`, and `DeepReadonly`.
+- Queries: `Selector`, `SelectorValue`, `ComparisonSelector`, `StringSelector`,
+  `NumericSelector`, `ArraySelector`, `LogicalSelector`, `FieldPath`,
+  `ValueAtPath`, and `MatchResult`.
+- Results: `FindOptions`, `Projection`, `SortSpecifier`, `SortDirection`,
+  `CollationOptions`, and `CollectionCursor`.
+- Mutations: `Modifier`, `UpdateOptions`, `UpsertOptions`, and `UpsertResult`.
+- Events: `CollectionInsertEvent`, `CollectionUpdateEvent`,
+  `CollectionRemoveEvent`, `CursorAddedEvent`, `CursorChangedEvent`, and
+  `CursorRemovedEvent`.
+
+The store is intentionally local-only and in-memory. It does not provide
+persistence, indexes, aggregation, transport synchronization, publications, or
+implicit React bindings.
+
+## Migrating from the former API
+
+- Change every document identity to a lowercase 24-character hexadecimal
+  string and remove uses of the former object identity class.
+- Replace observer callback objects with `cursor.on(...)` listeners.
+- Replace `fields` with `projection`; cursor events are always reactive.
+- Remove compatibility runtime factories, component overrides, observer
+  pause/resume calls, original-document tracking, mutation callbacks, predicate
+  selectors, and `$where` selectors.
+- Treat returned documents as immutable snapshots and perform all changes
+  through collection mutations.
+
+See `NOTICE.md` for required attribution covering inherited algorithmic work.

package/dist/minimongo/components.d.ts

@@ -0,0 +1,31 @@
+import { type DocumentStoreFactory } from './document-store.js';
+import { type IdentityCodec } from './identity.js';
+import { Matcher } from './matcher.js';
+import { type ModifyOptions } from './modifier.js';
+import { type ProjectionFunction } from './projection.js';
+import { Sorter } from './sorter.js';
+import type { CollationOptions, Modifier, Projection, Selector, SortSpecifier } from './types.js';
+import { type ValueSemantics } from './value-semantics.js';
+export interface QueryEngine {
+    matcher<TDocument extends object>(selector: Selector<TDocument> | unknown, options?: {
+        readonly isUpdate?: boolean;
+        readonly collation?: CollationOptions;
+    }): Matcher<TDocument>;
+    sorter<TDocument extends object>(sort: SortSpecifier<TDocument> | unknown, collation?: CollationOptions): Sorter<TDocument>;
+    projection<TDocument extends object>(projection?: Projection<TDocument> | Record<string, unknown>): ProjectionFunction<TDocument>;
+}
+export interface MutationEngine {
+    modify<TDocument extends Record<string, unknown>>(document: TDocument, modifier: Modifier<TDocument> | Partial<TDocument> | unknown, options?: ModifyOptions): void;
+    createUpsert<TDocument extends Record<string, unknown>>(selector: unknown, modifier: Modifier<TDocument> | Partial<TDocument>): TDocument;
+}
+export interface LocalStoreRuntime {
+    readonly values: ValueSemantics;
+    readonly identities: IdentityCodec<unknown>;
+    readonly documentStoreFactory: DocumentStoreFactory;
+    readonly query: QueryEngine;
+    readonly mutations: MutationEngine;
+    readonly randomId: () => string;
+    readonly now: () => Date;
+}
+export declare const LOCAL_STORE_RUNTIME: unique symbol;
+export declare const localStoreRuntime: LocalStoreRuntime;

package/dist/minimongo/components.js

@@ -0,0 +1,53 @@
+import { MemoryDocumentStore } from './document-store.js';
+import { stringIdentityCodec } from './identity.js';
+import { Matcher } from './matcher.js';
+import { createUpsertDocument, modifyDocument } from './modifier.js';
+import { compileProjection } from './projection.js';
+import { Sorter } from './sorter.js';
+import { localValueSemantics } from './value-semantics.js';
+export const LOCAL_STORE_RUNTIME = Symbol('TypeFerryLocalStoreRuntime');
+function randomId() {
+    const bytes = new Uint8Array(12);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('');
+}
+function queryEngine(values) {
+    return {
+        matcher(selector, options) {
+            return new Matcher(selector, options?.isUpdate, options?.collation, values);
+        },
+        sorter(sort, collation) {
+            return new Sorter(sort, collation, values);
+        },
+        projection(projection) {
+            return compileProjection(projection, values);
+        },
+    };
+}
+function mutationEngine(values) {
+    return {
+        modify(document, modifier, options) {
+            modifyDocument(document, modifier, options, values);
+        },
+        createUpsert(selector, modifier) {
+            return createUpsertDocument(selector, modifier, values);
+        },
+    };
+}
+function documentStoreFactory(identities, values) {
+    return {
+        create() {
+            return new MemoryDocumentStore(identities, values);
+        },
+    };
+}
+export const localStoreRuntime = Object.freeze({
+    values: localValueSemantics,
+    identities: stringIdentityCodec,
+    documentStoreFactory: documentStoreFactory(stringIdentityCodec, localValueSemantics),
+    query: queryEngine(localValueSemantics),
+    mutations: mutationEngine(localValueSemantics),
+    randomId,
+    now: () => new Date(),
+});
+//# sourceMappingURL=components.js.map

package/dist/minimongo/components.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.js","sourceRoot":"","sources":["../../src/minimongo/components.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAiD,MAAM,kBAAkB,CAAA;AACrG,OAAO,EAAE,mBAAmB,EAAsB,MAAM,YAAY,CAAA;AACpE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAsB,MAAM,YAAY,CAAA;AACrF,OAAO,EAAE,iBAAiB,EAA2B,MAAM,cAAc,CAAA;AACzE,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAEjC,OAAO,EAAE,mBAAmB,EAAuB,MAAM,mBAAmB,CAAA;AAyC5E,MAAM,CAAC,MAAM,mBAAmB,GAAkB,MAAM,CAAC,4BAA4B,CAAC,CAAA;AAEtF,SAAS,QAAQ;IACf,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAA;IAChC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAA;IAE7B,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;AAC/E,CAAC;AAED,SAAS,WAAW,CAAC,MAAsB;IACzC,OAAO;QACL,OAAO,CAAC,QAAQ,EAAE,OAAO;YACvB,OAAO,IAAI,OAAO,CAChB,QAAQ,EACR,OAAO,EAAE,QAAQ,EACjB,OAAO,EAAE,SAAS,EAClB,MAAM,CACP,CAAA;QACH,CAAC;QACD,MAAM,CAAC,IAAI,EAAE,SAAS;YACpB,OAAO,IAAI,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,CAAA;QAC5C,CAAC;QACD,UAAU,CAAC,UAAU;YACnB,OAAO,iBAAiB,CAAC,UAAU,EAAE,MAAM,CAAC,CAAA;QAC9C,CAAC;KACF,CAAA;AACH,CAAC;AAED,SAAS,cAAc,CAAC,MAAsB;IAC5C,OAAO;QACL,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO;YAChC,cAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAA;QACrD,CAAC;QACD,YAAY,CAAC,QAAQ,EAAE,QAAQ;YAC7B,OAAO,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAA;QACzD,CAAC;KACF,CAAA;AACH,CAAC;AAED,SAAS,oBAAoB,CAC3B,UAAkC,EAClC,MAAsB;IAEtB,OAAO;QACL,MAAM;YACJ,OAAO,IAAI,mBAAmB,CAC5B,UAAgC,EAChC,MAAM,CACP,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAsB,MAAM,CAAC,MAAM,CAAC;IAChE,MAAM,EAAE,mBAAmB;IAC3B,UAAU,EAAE,mBAAmB;IAC/B,oBAAoB,EAAE,oBAAoB,CAAC,mBAAmB,EAAE,mBAAmB,CAAC;IACpF,KAAK,EAAE,WAAW,CAAC,mBAAmB,CAAC;IACvC,SAAS,EAAE,cAAc,CAAC,mBAAmB,CAAC;IAC9C,QAAQ;IACR,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE;CACtB,CAAC,CAAA"}

package/dist/minimongo/contracts.type-test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/minimongo/contracts.type-test.js

@@ -0,0 +1,21 @@
+import { LocalCollection, } from './index.js';
+const tasks = new LocalCollection();
+const id = tasks.insert({ title: 'Typed', nested: { done: false } });
+const document = tasks.findOne(id);
+const snapshot = tasks.find().fetch();
+tasks.on('insert', event => {
+    const insertedId = event.document._id;
+    void insertedId;
+    // @ts-expect-error Public snapshots are deeply readonly.
+    event.document.nested.done = true;
+});
+tasks.find().on('change', documents => {
+    const first = documents[0];
+    // @ts-expect-error Cursor snapshots are readonly arrays.
+    documents.push(first);
+});
+// @ts-expect-error Local collections accept only string IDs.
+tasks.insert({ _id: 1, title: 'Invalid', nested: { done: false } });
+void document;
+void snapshot;
+//# sourceMappingURL=contracts.type-test.js.map

package/dist/minimongo/contracts.type-test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.type-test.js","sourceRoot":"","sources":["../../src/minimongo/contracts.type-test.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,GAGhB,MAAM,SAAS,CAAA;AAShB,MAAM,KAAK,GAAG,IAAI,eAAe,EAAQ,CAAA;AACzC,MAAM,EAAE,GAAW,KAAK,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAA;AAC5E,MAAM,QAAQ,GAA2C,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;AAC1E,MAAM,QAAQ,GAAwD,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,CAAA;AAE1F,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE;IACzB,MAAM,UAAU,GAAW,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAA;IAC7C,KAAK,UAAU,CAAA;IAEf,yDAAyD;IACzD,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,GAAG,IAAI,CAAA;AACnC,CAAC,CAAC,CAAA;AAEF,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE;IACpC,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,CAAA;IAE1B,yDAAyD;IACzD,SAAS,CAAC,IAAI,CAAC,KAAM,CAAC,CAAA;AACxB,CAAC,CAAC,CAAA;AAEF,6DAA6D;AAC7D,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAA;AAEnE,KAAK,QAAQ,CAAA;AACb,KAAK,QAAQ,CAAA"}

package/dist/minimongo/cursor.d.ts

@@ -0,0 +1,67 @@
+import { LOCAL_STORE_RUNTIME, type LocalStoreRuntime } from './components.js';
+import { TypedEventEmitter } from './events.js';
+import { type DeepReadonly } from './immutable.js';
+import { Matcher } from './matcher.js';
+import type { FindOptions, MaterializedDocument, Selector, TransformedDocument } from './types.js';
+export interface CursorCollection<TDocument extends object> {
+    readonly name: string | undefined;
+    readonly [LOCAL_STORE_RUNTIME]: LocalStoreRuntime;
+    documents(): Iterable<TDocument>;
+    addObserver(observer: () => void): () => void;
+}
+export interface CursorAddedEvent<TDocument extends object> {
+    readonly document: TDocument;
+    readonly index: number;
+}
+export interface CursorChangedEvent<TDocument extends object> {
+    readonly previous: TDocument;
+    readonly document: TDocument;
+    readonly previousIndex: number;
+    readonly index: number;
+}
+export interface CursorRemovedEvent<TDocument extends object> {
+    readonly document: TDocument;
+    readonly index: number;
+}
+type CursorEvents<TDocument extends object> = {
+    change: readonly [documents: readonly TDocument[]];
+    added: readonly [event: CursorAddedEvent<TDocument>];
+    changed: readonly [event: CursorChangedEvent<TDocument>];
+    removed: readonly [event: CursorRemovedEvent<TDocument>];
+};
+/** A lazily evaluated query with event-driven immutable result snapshots. */
+export declare class Cursor<TDocument extends object, TOutput extends object = TDocument> extends TypedEventEmitter<CursorEvents<DeepReadonly<TransformedDocument<TDocument, TOutput>>>> implements Iterable<DeepReadonly<TransformedDocument<TDocument, TOutput>>>, AsyncIterable<DeepReadonly<TransformedDocument<TDocument, TOutput>>> {
+    private readonly collection;
+    private readonly options;
+    readonly matcher: Matcher<TDocument>;
+    private readonly projection;
+    private readonly transform;
+    private readonly sorter;
+    private readonly skip;
+    private readonly limit;
+    private previous;
+    private removeObserver;
+    private listenerCount;
+    constructor(collection: CursorCollection<TDocument>, selector: Selector<TDocument> | unknown, options?: FindOptions<TDocument, TOutput>);
+    count(): number;
+    countAsync(): Promise<number>;
+    fetch(): readonly DeepReadonly<TransformedDocument<TDocument, TOutput>>[];
+    fetchAsync(): Promise<readonly DeepReadonly<TransformedDocument<TDocument, TOutput>>[]>;
+    forEach(callback: (document: DeepReadonly<TransformedDocument<TDocument, TOutput>>, index: number, cursor: this) => void, thisArg?: unknown): void;
+    map<TResult>(callback: (document: DeepReadonly<TransformedDocument<TDocument, TOutput>>, index: number, cursor: this) => TResult, thisArg?: unknown): TResult[];
+    forEachAsync(callback: (document: DeepReadonly<TransformedDocument<TDocument, TOutput>>, index: number, cursor: this) => void | Promise<void>, thisArg?: unknown): Promise<void>;
+    mapAsync<TResult>(callback: (document: DeepReadonly<TransformedDocument<TDocument, TOutput>>, index: number, cursor: this) => TResult | Promise<TResult>, thisArg?: unknown): Promise<TResult[]>;
+    getTransform(): ((document: TDocument) => TransformedDocument<TDocument, TOutput>) | undefined;
+    [Symbol.iterator](): Iterator<DeepReadonly<TransformedDocument<TDocument, TOutput>>>;
+    [Symbol.asyncIterator](): AsyncIterator<DeepReadonly<TransformedDocument<TDocument, TOutput>>>;
+    /** Stops observing collection mutations while retaining current listeners. */
+    stop(): void;
+    protected onListenerAdded(): void;
+    protected onListenerRemoved(): void;
+    private handleMutation;
+    private rawDocuments;
+    private outputDocument;
+    private idOf;
+}
+export type CollectionCursor<TSchema extends object, TOutput extends object = MaterializedDocument<TSchema, string>> = Cursor<MaterializedDocument<TSchema, string>, TOutput>;
+export {};

package/dist/minimongo/cursor.js

@@ -0,0 +1,157 @@
+import { LOCAL_STORE_RUNTIME } from './components.js';
+import { TypedEventEmitter } from './events.js';
+import { deepFreeze } from './immutable.js';
+import { Matcher } from './matcher.js';
+import { wrapTransform } from './transform.js';
+/** A lazily evaluated query with event-driven immutable result snapshots. */
+export class Cursor extends TypedEventEmitter {
+    collection;
+    options;
+    matcher;
+    projection;
+    transform;
+    sorter;
+    skip;
+    limit;
+    previous;
+    removeObserver;
+    listenerCount = 0;
+    constructor(collection, selector, options = {}) {
+        super();
+        this.collection = collection;
+        this.options = options;
+        this.matcher = collection[LOCAL_STORE_RUNTIME].query.matcher(selector, {
+            ...(options.collation ? { collation: options.collation } : {}),
+        });
+        this.sorter = options.sort
+            ? collection[LOCAL_STORE_RUNTIME].query.sorter(options.sort, options.collation)
+            : this.matcher.hasGeoQuery()
+                ? collection[LOCAL_STORE_RUNTIME].query.sorter([], options.collation)
+                : undefined;
+        this.projection = collection[LOCAL_STORE_RUNTIME].query.projection(options.projection);
+        this.transform = wrapTransform(options.transform, collection[LOCAL_STORE_RUNTIME].values);
+        this.skip = options.skip ?? 0;
+        this.limit = options.limit;
+    }
+    count() {
+        return this.rawDocuments().length;
+    }
+    countAsync() {
+        return Promise.resolve(this.count());
+    }
+    fetch() {
+        return deepFreeze(this.rawDocuments().map(document => this.outputDocument(document)));
+    }
+    fetchAsync() {
+        return Promise.resolve(this.fetch());
+    }
+    forEach(callback, thisArg) {
+        this.fetch().forEach((document, index) => callback.call(thisArg, document, index, this));
+    }
+    map(callback, thisArg) {
+        return this.fetch().map((document, index) => callback.call(thisArg, document, index, this));
+    }
+    async forEachAsync(callback, thisArg) {
+        let index = 0;
+        for (const document of this.fetch()) {
+            await callback.call(thisArg, document, index, this);
+            index += 1;
+        }
+    }
+    async mapAsync(callback, thisArg) {
+        const results = [];
+        await this.forEachAsync(async (document, index) => {
+            results.push(await callback.call(thisArg, document, index, this));
+        });
+        return results;
+    }
+    getTransform() {
+        return this.transform;
+    }
+    [Symbol.iterator]() {
+        return this.fetch()[Symbol.iterator]();
+    }
+    [Symbol.asyncIterator]() {
+        const iterator = this[Symbol.iterator]();
+        return { next: async () => iterator.next() };
+    }
+    /** Stops observing collection mutations while retaining current listeners. */
+    stop() {
+        this.removeObserver?.();
+        this.removeObserver = undefined;
+        this.previous = undefined;
+    }
+    onListenerAdded() {
+        this.listenerCount += 1;
+        if (this.removeObserver)
+            return;
+        this.previous = this.fetch();
+        this.removeObserver = this.collection.addObserver(() => this.handleMutation());
+    }
+    onListenerRemoved() {
+        this.listenerCount = Math.max(0, this.listenerCount - 1);
+        if (this.listenerCount === 0)
+            this.stop();
+    }
+    handleMutation() {
+        const previous = this.previous ?? [];
+        const current = this.fetch();
+        const previousById = new Map(previous.map((document, index) => [this.idOf(document), { document, index }]));
+        const currentById = new Map(current.map((document, index) => [this.idOf(document), { document, index }]));
+        let changed = false;
+        for (const [id, entry] of previousById) {
+            if (currentById.has(id))
+                continue;
+            this.emit('removed', deepFreeze({ document: entry.document, index: entry.index }));
+            changed = true;
+        }
+        for (const [id, entry] of currentById) {
+            const old = previousById.get(id);
+            if (!old) {
+                this.emit('added', deepFreeze({ document: entry.document, index: entry.index }));
+                changed = true;
+            }
+            else if (old.document !== entry.document
+                && !this.collection[LOCAL_STORE_RUNTIME].values.equals(old.document, entry.document)) {
+                this.emit('changed', deepFreeze({
+                    previous: old.document,
+                    document: entry.document,
+                    previousIndex: old.index,
+                    index: entry.index,
+                }));
+                changed = true;
+            }
+            else if (old.index !== entry.index) {
+                changed = true;
+            }
+        }
+        this.previous = current;
+        if (changed)
+            this.emit('change', current);
+    }
+    rawDocuments() {
+        const distances = new Map();
+        const documents = [];
+        for (const document of this.collection.documents()) {
+            const result = this.matcher.documentMatches(document);
+            if (!result.result)
+                continue;
+            documents.push(document);
+            if (result.distance !== undefined)
+                distances.set(this.idOf(document), result.distance);
+        }
+        if (this.sorter)
+            documents.sort(this.sorter.getComparator({ distances }));
+        return documents.slice(this.skip, this.limit === undefined ? undefined : this.skip + this.limit);
+    }
+    outputDocument(document) {
+        const hasProjection = Object.keys(this.options.projection ?? {}).length > 0;
+        const projected = hasProjection ? this.projection(document) : document;
+        const output = this.transform ? this.transform(projected) : projected;
+        return deepFreeze(output);
+    }
+    idOf(document) {
+        return String(Reflect.get(document, '_id'));
+    }
+}
+//# sourceMappingURL=cursor.js.map