@travetto/model-indexed 8.0.0-alpha.10 → 8.0.0-alpha.12

package/README.md

@@ -136,7 +136,7 @@ export const specificOrders = keyedIndex(Order, {
 ```
 
 ## Using Indexes
-Model services that implement [ModelIndexedSupport](https://github.com/travetto/travetto/tree/main/module/model-indexed/src/types/service.ts#L23) allow you to query using the indexes you've defined.
+Model services that implement [ModelIndexedSupport](https://github.com/travetto/travetto/tree/main/module/model-indexed/src/types/service.ts#L15) allow you to query using the indexes you've defined.
 
 ### Service Interface
 
@@ -204,17 +204,36 @@ export interface ModelIndexedSupport extends ModelBasicSupport {
   >(cls: Class<T>, idx: SingleItemIndex<T, K, S>, body: FullKeyedIndexWithPartialBody<T, K, S>): Promise<T>;
 
   /**
-   * List entity by ranged index as defined by fields of idx
+   * Page through entities by ranged index as defined by fields of idx
+   *
+   * Note: Limit is generally honored, but can vary depending on the underlying storage implementation.
+   *
+   * @param cls The type to search by
+   * @param idx The index to search against
+   * @param body The payload of fields needed to search
+   * @param options The configuration for pagination
+   */
+  pageByIndex<
+    T extends ModelType,
+    S extends SortedIndexSelection<T>,
+    K extends KeyedIndexSelection<T>
+  >(cls: Class<T>, idx: SortedIndex<T, K, S>, body: KeyedIndexBody<T, K>, options?: ModelPageOptions): Promise<ModelPageResult<T>>;
+
+  /**
+   * List all entities by ranged index as defined by fields of idx
+   *
+   * Note: Limit is generally honored, but can vary depending on the underlying storage implementation.
+   * Batch size hint can be used to optimize batch size, but is not guaranteed.
+   *
    * @param cls The type to search by
    * @param idx The index to search against
    * @param body The payload of fields needed to search
-   * @param options The configuration for listing
    */
   listByIndex<
     T extends ModelType,
     S extends SortedIndexSelection<T>,
     K extends KeyedIndexSelection<T>
-  >(cls: Class<T>, idx: SortedIndex<T, K, S>, body: KeyedIndexBody<T, K>, options?: ListPageOptions): Promise<ListPageResult<T>>;
+  >(cls: Class<T>, idx: SortedIndex<T, K, S>, body: KeyedIndexBody<T, K>, options?: ModelListOptions): AsyncIterable<T[]>;
 }
 ```
 
@@ -224,41 +243,63 @@ The service provides these operations:
    *  `upsertByIndex` — Insert or update by index
    *  `updateByIndex` — Update an existing item by index
    *  `updatePartialByIndex` — Partially update an item by index
-   *  `listByIndex` — List items with pagination and sorting
+   *  `pageByIndex` — Fetch a page of items with pagination metadata
+   *  `listByIndex` — Stream matching items from a sorted index in batches, optionally capped by `limit`
 
 ### Getting Items
 Use `getByIndex` to fetch a single item by providing all required key fields.
 
 **Code: Getting by Keyed Index**
 ```typescript
-export async function getExample(modelService: any) {
+export async function getExample(modelService: ModelIndexedSupport) {
   const user = await modelService.getByIndex(User, userByName, {
     name: 'John Doe'
   });
   return user;
 }
+
+export async function getScopedExample(modelService: ModelIndexedSupport) {
+  const user = await modelService.getByIndex(User, userByName, {
+    name: 'John Doe',
+    id: 'user-123'
+  });
+  return user;
+}
 ```
 
-For sorted indexes with key fields, you must provide all key values plus the sort value if using it to identify a specific item.
+For sorted indexes with key fields, you must provide all key values plus the sort value if using it to identify a specific item. All single-item index operations also accept an optional `id` in the request body. This is useful when the index is not unique and you need to ensure the supplied index values resolve to the same record as the provided `id`, such as enforcing a pattern like "userId matches".
+
+**Code: Disambiguating with id**
+```typescript
+export async function getScopedExample(modelService: ModelIndexedSupport) {
+  const user = await modelService.getByIndex(User, userByName, {
+    name: 'John Doe',
+    id: 'user-123'
+  });
+  return user;
+}
+```
 
 ### Deleting Items
 Use `deleteByIndex` to remove an item by index.
 
 **Code: Deleting by Index**
 ```typescript
-export async function deleteExample(modelService: any) {
+export async function deleteExample(modelService: ModelIndexedSupport) {
   await modelService.deleteByIndex(User, userByName, {
     name: 'John Doe'
   });
 }
 ```
 
+As with `getByIndex`, you can pass an optional `id` to ensure the computed index values resolve to the expected record before deleting it.
+
 ### Upserting Items
 Use `upsertByIndex` to insert a new item or update an existing one. The index acts as a primary key.
 
 **Code: Upserting by Index**
 ```typescript
-export async function upsertExample(modelService: any) {
+export async function upsertExample(modelService: ModelIndexedSupport) {
   const user = await modelService.upsertByIndex(User, userByName, {
     id: 'user-1',
     name: 'John Doe',
@@ -273,7 +314,7 @@ Use `updateByIndex` to update an existing item, or `updatePartialByIndex` for pa
 
 **Code: Updating by Index**
 ```typescript
-export async function updateExample(modelService: any) {
+export async function updateExample(modelService: ModelIndexedSupport) {
   // Full update — all fields required
   const user = await modelService.updateByIndex(User, userByName, {
     id: 'user-1',
@@ -284,7 +325,7 @@ export async function updateExample(modelService: any) {
   return user;
 }
 
-export async function updatePartialExample(modelService: any) {
+export async function updatePartialExample(modelService: ModelIndexedSupport) {
   // Partial update — only updated fields required
   const user = await modelService.updatePartialByIndex(User, userByName, {
     name: 'John Doe',
@@ -295,12 +336,12 @@ export async function updatePartialExample(modelService: any) {
 ```
 
 ### Listing Items
-Use `listByIndex` to fetch multiple items from a sorted index with pagination.
+Use `pageByIndex` when you want paginated access to a sorted index.
 
-**Code: Listing by Sorted Index**
+**Code: Paging by Sorted Index**
 ```typescript
-export async function listExample(modelService: any) {
-  const result = await modelService.listByIndex(User, recentUsers, {}, {
+export async function listExample(modelService: ModelIndexedSupport) {
+  const result = await modelService.pageByIndex(User, recentUsers, {}, {
     limit: 20,
     offset: '0'
   });
@@ -311,13 +352,28 @@ export async function listExample(modelService: any) {
 }
 ```
 
-You can also provide key values to filter within a sorted index:
+Use `listByIndex` when you want to iterate through matching items as an async stream of batches.  The same list options used by `list` are supported here, including `limit` when you want to stop after a fixed number of records.
+
+**Code: Streaming by Sorted Index**
+```typescript
+export async function listStreamExample(modelService: ModelIndexedSupport) {
+  const items: User[] = [];
+
+  for await (const batch of modelService.listByIndex(User, recentUsers, {}, { limit: 25 })) {
+    items.push(...batch);
+  }
+
+  return items;
+}
+```
+
+You can also provide key values to filter within a sorted index with `pageByIndex`:
 
 **Code: Listing with Key Filter**
 ```typescript
-export async function listWithFilterExample(modelService: any) {
+export async function listWithFilterExample(modelService: ModelIndexedSupport) {
   // Get all users named 'John' sorted by age
-  const result = await modelService.listByIndex(User, usersByNameAge, {
+  const result = await modelService.pageByIndex(User, usersByNameAge, {
     name: 'John'
   }, {
     limit: 10
@@ -327,7 +383,7 @@ export async function listWithFilterExample(modelService: any) {
 ```
 
 ## Integration
-Index registration happens automatically when models are decorated with [@Model](https://github.com/travetto/travetto/tree/main/module/model/src/registry/decorator.ts#L14). Model services like [Memory Model Support](https://github.com/travetto/travetto/tree/main/module/model-memory#readme "Memory backing for the travetto model module."), [MongoDB Model Support](https://github.com/travetto/travetto/tree/main/module/model-mongo#readme "Mongo backing for the travetto model module."), and [SQL Model Service](https://github.com/travetto/travetto/tree/main/module/model-sql#readme "SQL backing for the travetto model module, with real-time modeling support for SQL schemas.") implement the [ModelIndexedSupport](https://github.com/travetto/travetto/tree/main/module/model-indexed/src/types/service.ts#L23) interface to provide indexed access.
+Index registration happens automatically when models are decorated with [@Model](https://github.com/travetto/travetto/tree/main/module/model/src/registry/decorator.ts#L14). Model services like [Memory Model Support](https://github.com/travetto/travetto/tree/main/module/model-memory#readme "Memory backing for the travetto model module."), [MongoDB Model Support](https://github.com/travetto/travetto/tree/main/module/model-mongo#readme "Mongo backing for the travetto model module."), and [SQL Model Service](https://github.com/travetto/travetto/tree/main/module/model-sql#readme "SQL backing for the travetto model module, with real-time modeling support for SQL schemas.") implement the [ModelIndexedSupport](https://github.com/travetto/travetto/tree/main/module/model-indexed/src/types/service.ts#L15) interface to provide indexed access.
 
 ### Reading Registry Information
 You can access registered indexes via [ModelRegistryIndex](https://github.com/travetto/travetto/tree/main/module/model/src/registry/registry-index.ts#L12) at runtime:
@@ -335,11 +391,11 @@ You can access registered indexes via [ModelRegistryIndex](https://github.com/tr
 **Code: Accessing Model Indexes**
 ```typescript
 export function registryAccessExample() {
-  const registry = ModelRegistryIndex.get(User);
+  const registry = ModelRegistryIndex.getConfig(User);
   const indexes = registry.indices; // Map of all indexes for the model
 
   // Access a specific index
-  const userByName = indexes['userByName'];
+  const userByName = indexes?.['userByName'];
   return userByName;
 }
 ```
@@ -350,4 +406,4 @@ export function registryAccessExample() {
    *  **Use composite keys** — When filtering by multiple fields, include all of them in a single index
    *  **Leverage sorting** — Use sorted indexes for paginated lists and range queries
    *  **Enforce uniqueness** — Use [uniqueIndex](https://github.com/travetto/travetto/tree/main/module/model-indexed/src/indexes.ts#L47) for fields that must be globally unique
-   *  **Handle errors gracefully** — Catch [IndexedFieldError](https://github.com/travetto/travetto/tree/main/module/model-indexed/src/types/indexes.ts#L88) when working with user input
+   *  **Handle errors gracefully** — Catch [IndexedFieldError](https://github.com/travetto/travetto/tree/main/module/model-indexed/src/types/error.ts#L7) when working with user input

package/__index__.ts

@@ -1,4 +1,6 @@
+export * from './src/types/error.ts';
 export * from './src/types/indexes.ts';
+export * from './src/types/list.ts';
 export * from './src/types/service.ts';
 export * from './src/computed.ts';
 export * from './src/indexes.ts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/model-indexed",
-  "version": "8.0.0-alpha.10",
+  "version": "8.0.0-alpha.12",
   "type": "module",
   "description": "Basic indexing support for model sources that support it.",
   "keywords": [
@@ -26,13 +26,13 @@
     "directory": "module/model-indexed"
   },
   "dependencies": {
-    "@travetto/model": "^8.0.0-alpha.10",
-    "@travetto/registry": "^8.0.0-alpha.10",
-    "@travetto/schema": "^8.0.0-alpha.10"
+    "@travetto/model": "^8.0.0-alpha.11",
+    "@travetto/registry": "^8.0.0-alpha.11",
+    "@travetto/schema": "^8.0.0-alpha.11"
   },
   "peerDependencies": {
-    "@travetto/cli": "^8.0.0-alpha.15",
-    "@travetto/test": "^8.0.0-alpha.10"
+    "@travetto/cli": "^8.0.0-alpha.16",
+    "@travetto/test": "^8.0.0-alpha.11"
   },
   "peerDependenciesMeta": {
     "@travetto/cli": {

package/src/computed.ts

@@ -2,15 +2,16 @@ import type { ModelType } from '@travetto/model';
 import { castTo, type Any } from '@travetto/runtime';
 
 import {
-  type KeyedIndexSelection, type SortedIndexSelection, type AllIndexes, type KeyedIndexBody, IndexedFieldError,
+  type KeyedIndexSelection, type SortedIndexSelection, type AllIndexes, type KeyedIndexBody,
   type FullKeyedIndexBody, type TemplateValue, type TemplatePart
 } from './types/indexes.ts';
+import { IndexedFieldError } from './types/error.ts';
 
 const DEFAULT_SEP = '\u8203';
 
-type IndexPart<T extends TemplateValue = TemplateValue> = {
+type IndexPart<T extends TemplateValue = TemplateValue, V = unknown> = {
   state: 'missing' | 'empty' | 'mismatch' | 'found';
-  value: unknown;
+  value: V;
   path: string[];
   templateValue: T;
 };
@@ -29,11 +30,11 @@ function buildIndexParts<T extends TemplateValue = TemplateValue>(
         if (value && pathItem in value) {
           value = castTo<Record<string, unknown>>(value)[pathItem];
         } else {
-          bodyPart = { value: undefined!, state: 'missing' };
+          bodyPart = { value: null, state: 'missing' };
           break;
         }
       } else {
-        bodyPart = { value: undefined!, state: 'mismatch' };
+        bodyPart = { value: castTo(value), state: 'mismatch' };
         break;
       }
     }
@@ -75,6 +76,7 @@ export class ModelIndexedComputedIndex<T extends ModelType> {
 
   keyedParts: IndexPart<true>[];
   sortParts: IndexPart<-1 | 1>[];
+  idPart: IndexPart<true, string> | undefined;
   idx: AllIndexes<T>;
 
   constructor(
@@ -84,6 +86,9 @@ export class ModelIndexedComputedIndex<T extends ModelType> {
     this.idx = idx;
     this.keyedParts = buildIndexParts(idx.keyTemplate, castTo(body));
     this.sortParts = buildIndexParts(idx.sortTemplate, castTo(body), value => typeof value === 'number' || value instanceof Date);
+    if ('id' in body && typeof body.id === 'string') {
+      this.idPart = { path: ['id'], value: body.id, state: body.id === null || body.id === undefined ? 'empty' : 'found', templateValue: true };
+    }
   }
 
   get allParts(): IndexPart[] {
@@ -119,8 +124,8 @@ export class ModelIndexedComputedIndex<T extends ModelType> {
     }
   }
 
-  project(config: IndexProcessConfig<{ emptyValue?: unknown }> = {}): Record<string, unknown> {
-    const { keyed = true, sort = false, emptyValue = null } = config;
+  project(config: IndexProcessConfig<{ emptyValue?: unknown, includeId?: boolean }> = {}): Record<string, unknown> {
+    const { keyed = true, sort = false, emptyValue = null, includeId } = config;
     const response: Record<string, unknown> = {};
     if (keyed) {
       for (const { path, value, state } of this.keyedParts) {
@@ -144,6 +149,9 @@ export class ModelIndexedComputedIndex<T extends ModelType> {
         sub[last] = state === 'empty' ? emptyValue : value;
       }
     }
+    if (includeId && this.idPart) {
+      response.id = this.idPart.state === 'empty' ? emptyValue : this.idPart.value;
+    }
     return response;
   }
 }

package/src/types/error.ts

@@ -0,0 +1,13 @@
+import type { ModelType } from '@travetto/model';
+import { RuntimeError, type Class } from '@travetto/runtime';
+
+import type { AllIndexes } from './indexes.ts';
+
+
+export class IndexedFieldError<T extends ModelType> extends RuntimeError {
+  constructor(cls: Class<T>, idx: AllIndexes<T>, fieldPath: string, message: string) {
+    super(`${message}:  ${idx.name} on ${cls.name} at path ${fieldPath}`, {
+      details: { cls: cls.name, index: idx.name, fieldPath }
+    });
+  }
+}

package/src/types/indexes.ts

@@ -1,5 +1,5 @@
 import type { ModelType, IndexConfig } from '@travetto/model';
-import { type IntrinsicType, type Any, type DeepPartial, RuntimeError, type Class } from '@travetto/runtime';
+import { type IntrinsicType, type Any, type DeepPartial } from '@travetto/runtime';
 
 type TypeProjection<T, V> = {
   [P in keyof T]?:
@@ -10,8 +10,8 @@ type TypeProjection<T, V> = {
   );
 };
 
-export type KeyedIndexSelection<T> = TypeProjection<T, true>;
-export type SortedIndexSelection<T> = TypeProjection<T, 1 | -1>;
+export type KeyedIndexSelection<T extends ModelType> = TypeProjection<T, true>;
+export type SortedIndexSelection<T extends ModelType> = TypeProjection<T, 1 | -1>;
 
 export type KeyedIndexBody<T, K> = {
   [P in keyof K]: (P extends keyof T ?
@@ -44,8 +44,8 @@ export type KeyedIndexWithPartialBody<T, K> = {
   DeepPartial<Omit<T, keyof K>>;
 
 
-export type FullKeyedIndexBody<T, K, S> = KeyedIndexBody<T, Merge<K, S>>;
-export type FullKeyedIndexWithPartialBody<T, K, S> = KeyedIndexWithPartialBody<T, Merge<K, S>>;
+export type FullKeyedIndexBody<T, K, S> = KeyedIndexBody<Omit<T, 'id'>, Merge<K, S>> & { id?: string };
+export type FullKeyedIndexWithPartialBody<T, K, S> = KeyedIndexWithPartialBody<Omit<T, 'id'>, Merge<K, S>> & { id?: string };
 
 export type TemplateValue = 1 | -1 | true;
 export type TemplatePart<T extends TemplateValue = TemplateValue> = { path: string[], value: T, part: 'key' | 'sort' };
@@ -85,10 +85,3 @@ export type AllIndexes<
   S extends SortedIndexSelection<T> = Any
 > = KeyedIndex<T, K, S> | SortedIndex<T, K, S>;
 
-export class IndexedFieldError<T extends ModelType> extends RuntimeError {
-  constructor(cls: Class<T>, idx: AllIndexes<T>, fieldPath: string, message: string) {
-    super(`${message}:  ${idx.name} on ${cls.name} at path ${fieldPath}`, {
-      details: { cls: cls.name, index: idx.name, fieldPath }
-    });
-  }
-}

package/src/types/list.ts

@@ -0,0 +1,12 @@
+import type { ModelType } from '@travetto/model';
+
+export interface ModelPageOptions<O = string> {
+  batchSizeHint?: number;
+  limit?: number;
+  offset?: O;
+}
+
+export interface ModelPageResult<T extends ModelType> {
+  items: T[];
+  nextOffset?: string;
+}

package/src/types/service.ts

@@ -1,19 +1,11 @@
-import type { ModelType, ModelBasicSupport, OptionalId } from '@travetto/model';
+import type { ModelType, ModelBasicSupport, OptionalId, ModelListOptions } from '@travetto/model';
 import type { Class } from '@travetto/runtime';
+
 import type {
   KeyedIndexSelection, KeyedIndexBody, SortedIndexSelection, SortedIndex,
   SingleItemIndex, FullKeyedIndexBody, FullKeyedIndexWithPartialBody
 } from './indexes.ts';
-
-export type ListPageOptions<O = string> = {
-  limit?: number;
-  offset?: O;
-};
-
-export type ListPageResult<T extends ModelType> = {
-  items: T[];
-  nextOffset?: string;
-};
+import type { ModelPageOptions, ModelPageResult } from './list.ts';
 
 /**
  * Support for simple indexed activity
@@ -82,15 +74,34 @@ export interface ModelIndexedSupport extends ModelBasicSupport {
   >(cls: Class<T>, idx: SingleItemIndex<T, K, S>, body: FullKeyedIndexWithPartialBody<T, K, S>): Promise<T>;
 
   /**
-   * List entity by ranged index as defined by fields of idx
+   * Page through entities by ranged index as defined by fields of idx
+   *
+   * Note: Limit is generally honored, but can vary depending on the underlying storage implementation.
+   *
+   * @param cls The type to search by
+   * @param idx The index to search against
+   * @param body The payload of fields needed to search
+   * @param options The configuration for pagination
+   */
+  pageByIndex<
+    T extends ModelType,
+    S extends SortedIndexSelection<T>,
+    K extends KeyedIndexSelection<T>
+  >(cls: Class<T>, idx: SortedIndex<T, K, S>, body: KeyedIndexBody<T, K>, options?: ModelPageOptions): Promise<ModelPageResult<T>>;
+
+  /**
+   * List all entities by ranged index as defined by fields of idx
+   *
+   * Note: Limit is generally honored, but can vary depending on the underlying storage implementation.
+   * Batch size hint can be used to optimize batch size, but is not guaranteed.
+   *
    * @param cls The type to search by
    * @param idx The index to search against
    * @param body The payload of fields needed to search
-   * @param options The configuration for listing
    */
   listByIndex<
     T extends ModelType,
     S extends SortedIndexSelection<T>,
     K extends KeyedIndexSelection<T>
-  >(cls: Class<T>, idx: SortedIndex<T, K, S>, body: KeyedIndexBody<T, K>, options?: ListPageOptions): Promise<ListPageResult<T>>;
+  >(cls: Class<T>, idx: SortedIndex<T, K, S>, body: KeyedIndexBody<T, K>, options?: ModelListOptions): AsyncIterable<T[]>;
 }

package/support/test/indexed.ts

@@ -1,4 +1,5 @@
 import assert from 'node:assert';
+import timers from 'node:timers/promises';
 
 import { Suite, Test } from '@travetto/test';
 import { Schema } from '@travetto/schema';
@@ -8,7 +9,7 @@ import { BaseModelSuite } from '@travetto/model/support/test/base.ts';
 
 import type { ModelIndexedSupport } from '../../src/types/service.ts';
 import { keyedIndex, sortedIndex } from '../../src/indexes.ts';
-import { IndexedFieldError } from '../../__index__.ts';
+import { IndexedFieldError } from '../../src/types/error.ts';
 
 @Model('index_user')
 class User {
@@ -102,6 +103,33 @@ export abstract class ModelIndexedSuite extends BaseModelSuite<ModelIndexedSuppo
     assert(found2.name === 'bob2');
   }
 
+  @Test()
+  async readByKeyedIndexUsingId() {
+    const service = await this.service;
+
+    const first = await service.create(User, User.from({ name: 'sam' }));
+    const second = await service.create(User, User.from({ name: 'bob' }));
+
+    const found = await service.getByIndex(User, userNameIndex, {
+      name: 'bob',
+      id: second.id
+    });
+
+    assert(found.id === second.id);
+
+    await assert.rejects(
+      () => service.getByIndex(User, userNameIndex, { name: 'bob', id: first.id }),
+      NotFoundError
+    );
+
+    await service.deleteByIndex(User, userNameIndex, { name: 'sam', id: first.id });
+
+    await assert.rejects(() => service.get(User, first.id), NotFoundError);
+
+    const remaining = await service.getByIndex(User, userNameIndex, { name: 'bob', id: second.id });
+    assert(remaining.id === second.id);
+  }
+
   @Test()
   async readMissingValue() {
     const service = await this.service;
@@ -133,6 +161,30 @@ export abstract class ModelIndexedSuite extends BaseModelSuite<ModelIndexedSuppo
     await assert.rejects(() => service.getByIndex(User3, userAgeIndex, { name: 'bob' }), IndexedFieldError);
   }
 
+  @Test()
+  async readBySortedIndexUsingId() {
+    const service = await this.service;
+
+    const first = await service.create(User3, User3.from({ name: 'bob', age: 40, color: 'blue' }));
+    const second = await service.create(User3, User3.from({ name: 'bob', age: 40, color: 'green' }));
+
+    const found = await service.getByIndex(User3, userAgeIndex, {
+      name: 'bob',
+      age: 40,
+      id: second.id
+    });
+
+    assert(found.id === second.id);
+    assert(found.color === 'green');
+
+    await service.deleteByIndex(User3, userAgeIndex, { name: 'bob', age: 40, id: first.id });
+
+    await assert.rejects(() => service.get(User3, first.id), NotFoundError);
+
+    const remaining = await service.getByIndex(User3, userAgeIndex, { name: 'bob', age: 40, id: second.id });
+    assert(remaining.id === second.id);
+  }
+
   @Test()
   async queryList() {
     const service = await this.service;
@@ -141,7 +193,7 @@ export abstract class ModelIndexedSuite extends BaseModelSuite<ModelIndexedSuppo
     await service.create(User3, User3.from({ name: 'bob', age: 30, color: 'red' }));
     await service.create(User3, User3.from({ name: 'bob', age: 50, color: 'green' }));
 
-    const { items: arr } = await service.listByIndex(User3, userAgeIndex, { name: 'bob' });
+    const { items: arr } = await service.pageByIndex(User3, userAgeIndex, { name: 'bob' });
 
     console.error(arr);
 
@@ -153,7 +205,7 @@ export abstract class ModelIndexedSuite extends BaseModelSuite<ModelIndexedSuppo
     assert(arr[2].name === 'bob');
 
     // @ts-expect-error
-    await assert.rejects(() => service.listByIndex(User3, userAgeIndex, {}), IndexedFieldError);
+    await assert.rejects(() => service.pageByIndex(User3, userAgeIndex, {}), IndexedFieldError);
   }
 
   @Test()
@@ -164,7 +216,7 @@ export abstract class ModelIndexedSuite extends BaseModelSuite<ModelIndexedSuppo
     await service.create(User3, User3.from({ name: 'alice', age: 30, color: 'red' }));
     await service.create(User3, User3.from({ name: 'bob', age: 50, color: 'green' }));
 
-    const { items: arr } = await service.listByIndex(User3, userAgeNoKeyIndex, {});
+    const { items: arr } = await service.pageByIndex(User3, userAgeNoKeyIndex, {});
 
     assert(arr[0].name === 'alice' && arr[0].age === 30);
     assert(arr[1].name === 'charlie' && arr[1].age === 40);
@@ -185,13 +237,13 @@ export abstract class ModelIndexedSuite extends BaseModelSuite<ModelIndexedSuppo
     await service.create(User4, User4.from({ child: { name: 'bob', age: 30 }, color: 'red' }));
     await service.create(User4, User4.from({ child: { name: 'bob', age: 50 }, color: 'green' }));
 
-    const { items: arr } = await service.listByIndex(User4, childAgeIndex, { child: { name: 'bob' } });
+    const { items: arr } = await service.pageByIndex(User4, childAgeIndex, { child: { name: 'bob' } });
     assert(arr[0].color === 'red' && arr[0].child.name === 'bob' && arr[0].child.age === 30);
     assert(arr[1].color === 'blue' && arr[1].child.name === 'bob' && arr[1].child.age === 40);
     assert(arr[2].color === 'green' && arr[2].child.name === 'bob' && arr[2].child.age === 50);
 
     // @ts-expect-error
-    await assert.rejects(() => service.listByIndex(User4, childAgeIndex, {}), IndexedFieldError);
+    await assert.rejects(() => service.pageByIndex(User4, childAgeIndex, {}), IndexedFieldError);
   }
 
   @Test({ skip: (self) => !castTo<ModelIndexedSuite>(self).supportsDeepIndexes })
@@ -202,14 +254,14 @@ export abstract class ModelIndexedSuite extends BaseModelSuite<ModelIndexedSuppo
     await service.create(User4, User4.from({ child: { name: 'bob', age: 30 }, createdDate: TimeUtil.fromNow('2d'), color: 'red' }));
     await service.create(User4, User4.from({ child: { name: 'bob', age: 50 }, createdDate: TimeUtil.fromNow('-1d'), color: 'green' }));
 
-    const { items: arr } = await service.listByIndex(User4, nameCreatedIndex, { child: { name: 'bob' } });
+    const { items: arr } = await service.pageByIndex(User4, nameCreatedIndex, { child: { name: 'bob' } });
 
     assert(arr[0].color === 'green' && arr[0].child.name === 'bob' && arr[0].child.age === 50);
     assert(arr[1].color === 'red' && arr[1].child.name === 'bob' && arr[1].child.age === 30);
     assert(arr[2].color === 'blue' && arr[2].child.name === 'bob' && arr[2].child.age === 40);
 
     // @ts-expect-error
-    await assert.rejects(() => service.listByIndex(User4, nameCreatedIndex, {}), IndexedFieldError);
+    await assert.rejects(() => service.pageByIndex(User4, nameCreatedIndex, {}), IndexedFieldError);
   }
 
   @Test()
@@ -220,7 +272,7 @@ export abstract class ModelIndexedSuite extends BaseModelSuite<ModelIndexedSuppo
     const user2 = await service.upsertByIndex(User3, userAgeIndex, { name: 'bob', age: 40, color: 'green' });
     const user3 = await service.upsertByIndex(User3, userAgeIndex, { name: 'bob', age: 40, color: 'red' });
 
-    const { items: arr } = await service.listByIndex(User3, userAgeIndex, { name: 'bob' });
+    const { items: arr } = await service.pageByIndex(User3, userAgeIndex, { name: 'bob' });
     assert(arr.length === 1);
 
     assert(user1.id === user2.id);
@@ -229,12 +281,12 @@ export abstract class ModelIndexedSuite extends BaseModelSuite<ModelIndexedSuppo
     assert(user3.color === 'red');
 
     const user4 = await service.upsertByIndex(User3, userAgeIndex, { name: 'bob', age: 30, color: 'red' });
-    const { items: arr2 } = await service.listByIndex(User3, userAgeIndex, { name: 'bob' });
+    const { items: arr2 } = await service.pageByIndex(User3, userAgeIndex, { name: 'bob' });
     assert(arr2.length === 2);
 
     await service.deleteByIndex(User3, userAgeIndex, user1);
 
-    const { items: arr3 } = await service.listByIndex(User3, userAgeIndex, { name: 'bob' });
+    const { items: arr3 } = await service.pageByIndex(User3, userAgeIndex, { name: 'bob' });
     assert(arr3.length === 1);
     assert(arr3[0].id === user4.id);
   }
@@ -288,7 +340,7 @@ export abstract class ModelIndexedSuite extends BaseModelSuite<ModelIndexedSuppo
     let offset: string | undefined;
 
     do {
-      const page = await service.listByIndex(User3, userAgeIndex, { name: 'page' }, { limit, offset });
+      const page = await service.pageByIndex(User3, userAgeIndex, { name: 'page' }, { limit, offset });
       items.push(...page.items.map(u => u.color!));
       offset = page.nextOffset;
     } while (offset);
@@ -312,7 +364,7 @@ export abstract class ModelIndexedSuite extends BaseModelSuite<ModelIndexedSuppo
     let offset: string | undefined;
 
     do {
-      const page = await service.listByIndex(User3, userAgeReversedIndex, { name: 'page' }, { limit, offset });
+      const page = await service.pageByIndex(User3, userAgeReversedIndex, { name: 'page' }, { limit, offset });
       items.push(...page.items.map(u => u.color!));
       offset = page.nextOffset;
     } while (offset);
@@ -320,4 +372,28 @@ export abstract class ModelIndexedSuite extends BaseModelSuite<ModelIndexedSuppo
     assert(items.length === allColors.length);
     assert.deepEqual(items, allColors.toReversed());
   }
+
+  @Test()
+  async listByIndexAbortSignal() {
+    const service = await this.service;
+
+    await Promise.all(
+      [20, 30, 40].map(age => service.create(User3, User3.from({ name: 'page', age, color: `${age}` })))
+    );
+
+    const controller = new AbortController();
+    const found: User3[] = [];
+
+    for await (const items of service.listByIndex(User3, userAgeIndex, { name: 'page' }, { abort: controller.signal, batchSizeHint: 1 })) {
+      found.push(...items);
+      controller.abort();
+      await timers.setTimeout(10);
+    }
+
+    if (this.indexLimitSkew) {
+      assert(found.length < this.indexLimitSkew && found.length > 0);
+    } else {
+      assert(found.length === 1);
+    }
+  }
 }