@travetto/model 8.0.0-alpha.2 → 8.0.0-alpha.21

package/README.md

@@ -16,7 +16,7 @@ yarn add @travetto/model
 This module provides a set of contracts/interfaces to data model persistence, modification and retrieval.  This module builds heavily upon the [Schema](https://github.com/travetto/travetto/tree/main/module/schema#readme "Data type registry for runtime validation, reflection and binding."), which is used for data model validation.
 
 ## A Simple Model
-A model can be simply defined by usage of the [@Model](https://github.com/travetto/travetto/tree/main/module/model/src/registry/decorator.ts#L14) decorator, which opts it into the [Schema](https://github.com/travetto/travetto/tree/main/module/schema#readme "Data type registry for runtime validation, reflection and binding.") contracts, as well as making it available to the [ModelRegistryIndex](https://github.com/travetto/travetto/tree/main/module/model/src/registry/registry-index.ts#L16).
+A model can be simply defined by usage of the [@Model](https://github.com/travetto/travetto/tree/main/module/model/src/registry/decorator.ts#L14) decorator, which opts it into the [Schema](https://github.com/travetto/travetto/tree/main/module/schema#readme "Data type registry for runtime validation, reflection and binding.") contracts, as well as making it available to the [ModelRegistryIndex](https://github.com/travetto/travetto/tree/main/module/model/src/registry/registry-index.ts#L12).
 
 **Code: Basic Structure**
 ```typescript
@@ -33,7 +33,7 @@ export class SampleModel {
 Once the model is defined, it can be leveraged with any of the services that implement the various model storage contracts.  These contracts allow for persisting and fetching of the associated model object.
 
 ## Contracts
-The module is mainly composed of contracts.  The contracts define the expected interface for various model patterns. The primary contracts are [Basic](https://github.com/travetto/travetto/tree/main/module/model/src/types/basic.ts#L8), [CRUD](https://github.com/travetto/travetto/tree/main/module/model/src/types/crud.ts#L11), [Indexed](https://github.com/travetto/travetto/tree/main/module/model/src/types/indexed.ts#L11), [Expiry](https://github.com/travetto/travetto/tree/main/module/model/src/types/expiry.ts#L10), [Blob](https://github.com/travetto/travetto/tree/main/module/model/src/types/blob.ts#L8) and [Bulk](https://github.com/travetto/travetto/tree/main/module/model/src/types/bulk.ts#L64).
+The module is mainly composed of contracts.  The contracts define the expected interface for various model patterns. The primary contracts are [Basic](https://github.com/travetto/travetto/tree/main/module/model/src/types/basic.ts#L8), [CRUD](https://github.com/travetto/travetto/tree/main/module/model/src/types/crud.ts#L11), [Expiry](https://github.com/travetto/travetto/tree/main/module/model/src/types/expiry.ts#L10), [Blob](https://github.com/travetto/travetto/tree/main/module/model/src/types/blob.ts#L8) and [Bulk](https://github.com/travetto/travetto/tree/main/module/model/src/types/bulk.ts#L64).
 
 ### Basic
 All [Data Modeling Support](https://github.com/travetto/travetto/tree/main/module/model#readme "Datastore abstraction for core operations.") implementations, must honor the [Basic](https://github.com/travetto/travetto/tree/main/module/model/src/types/basic.ts#L8) contract to be able to participate in the model ecosystem.  This contract represents the bare minimum for a model service.
@@ -76,7 +76,7 @@ export interface ModelBasicSupport<C = unknown> {
 ```
 
 ### CRUD
-The [CRUD](https://github.com/travetto/travetto/tree/main/module/model/src/types/crud.ts#L11) contract, builds upon the basic contract, and is built around the idea of simple data retrieval and storage, to create a foundation for other services that need only basic support.  The model extension in [Authentication](https://github.com/travetto/travetto/tree/main/module/auth#readme "Authentication scaffolding for the Travetto framework"), is an example of a module that only needs create, read and delete, and so any implementation of [Data Modeling Support](https://github.com/travetto/travetto/tree/main/module/model#readme "Datastore abstraction for core operations.") that honors this contract, can be used with the [Authentication](https://github.com/travetto/travetto/tree/main/module/auth#readme "Authentication scaffolding for the Travetto framework") model extension.
+The [CRUD](https://github.com/travetto/travetto/tree/main/module/model/src/types/crud.ts#L11) contract, builds upon the basic contract, and is built around the idea of simple data retrieval and storage, to create a foundation for other services that need only basic support.  The model extension in [Authentication](https://github.com/travetto/travetto/tree/main/module/auth#readme "Authentication support for the Travetto framework"), is an example of a module that only needs create, read and delete, and so any implementation of [Data Modeling Support](https://github.com/travetto/travetto/tree/main/module/model#readme "Datastore abstraction for core operations.") that honors this contract, can be used with the [Authentication](https://github.com/travetto/travetto/tree/main/module/auth#readme "Authentication support for the Travetto framework") model extension.
 
 **Code: Crud Contract**
 ```typescript
@@ -110,51 +110,18 @@ export interface ModelCrudSupport extends ModelBasicSupport {
   updatePartial<T extends ModelType>(cls: Class<T>, item: Partial<T> & { id: string }, view?: string): Promise<T>;
 
   /**
-   * List all items
+   * List all items of a collection, results returned in batches of items.
+   *
+   * Note: Batch size hint can be used to optimize batch size, but is not guaranteed.
+   *
+   * @param cls The class to list
+   * @param options Options for listing
    */
-  list<T extends ModelType>(cls: Class<T>): AsyncIterable<T>;
+  list<T extends ModelType>(cls: Class<T>, options?: ModelListOptions): AsyncIterable<T[]>;
 }
 ```
 
-### Indexed
-Additionally, an implementation may support the ability for basic [Indexed](https://github.com/travetto/travetto/tree/main/module/model/src/types/indexed.ts#L11) queries. This is not the full featured query support of [Data Model Querying](https://github.com/travetto/travetto/tree/main/module/model-query#readme "Datastore abstraction for advanced query support."), but allowing for indexed lookups.  This does not support listing by index, but may be added at a later date.
-
-**Code: Indexed Contract**
-```typescript
-export interface ModelIndexedSupport extends ModelBasicSupport {
-  /**
-   * Get entity by index as defined by fields of idx and the body fields
-   * @param cls The type to search by
-   * @param idx The index name to search against
-   * @param body The payload of fields needed to search
-   */
-  getByIndex<T extends ModelType>(cls: Class<T>, idx: string, body: DeepPartial<T>): Promise<T>;
-
-  /**
-   * Delete entity by index as defined by fields of idx and the body fields
-   * @param cls The type to search by
-   * @param idx The index name to search against
-   * @param body The payload of fields needed to search
-   */
-  deleteByIndex<T extends ModelType>(cls: Class<T>, idx: string, body: DeepPartial<T>): Promise<void>;
-
-  /**
-   * List entity by ranged index as defined by fields of idx and the body fields
-   * @param cls The type to search by
-   * @param idx The index name to search against
-   * @param body The payload of fields needed to search
-   */
-  listByIndex<T extends ModelType>(cls: Class<T>, idx: string, body?: DeepPartial<T>): AsyncIterable<T>;
-
-  /**
-   * Upsert by index, allowing the index to act as a primary key
-   * @param cls The type to create for
-   * @param idx The index name to use
-   * @param body The document to potentially store
-   */
-  upsertByIndex<T extends ModelType>(cls: Class<T>, idx: string, body: OptionalId<T>): Promise<T>;
-}
-```
+The `list` operation returns batches of model records as an async stream.  It also accepts listing options such as `limit` to cap how many records are produced, alongside other runtime controls such as abort signals and batch size hints.
 
 ### Expiry
 Certain implementations will also provide support for automatic [Expiry](https://github.com/travetto/travetto/tree/main/module/model/src/types/expiry.ts#L10) of data at runtime.  This is extremely useful for temporary data as, and is used in the [Caching](https://github.com/travetto/travetto/tree/main/module/cache#readme "Caching functionality with decorators for declarative use.") module for expiring data accordingly.
@@ -213,12 +180,13 @@ export interface ModelBlobSupport {
   updateBlobMetadata(location: string, metadata: BinaryMetadata): Promise<void>;
 
   /**
-   * Produces an externally usable URL for sharing limited read access to a specific resource
+   * Produces an externally usable URL for sharing limited read access to a specific resource.
+   * If expiresIn is explicitly set to false, returns a direct/public URL.
    *
    * @param location The asset location to read from
-   * @param expiresIn Expiry
+   * @param expiresIn Expiry or false for public/direct URL
    */
-  getBlobReadUrl?(location: string, expiresIn?: TimeSpan): Promise<string>;
+  getBlobReadUrl?(location: string, expiresIn?: TimeSpan | false): Promise<string>;
 
   /**
    * Produces an externally usable URL for sharing allowing direct write access
@@ -302,8 +270,8 @@ export abstract class BaseModelSuite<T> {
     const svc = (await this.service);
     if (ModelCrudUtil.isSupported(svc)) {
       let i = 0;
-      for await (const __el of svc.list(cls)) {
-        i += 1;
+      for await (const batch of svc.list(cls)) {
+        i += batch.length;
       }
       return i;
     } else {
@@ -332,12 +300,12 @@ export abstract class BaseModelSuite<T> {
     return DependencyRegistryIndex.getInstance(this.serviceClass);
   }
 
-  async toArray<U>(src: AsyncIterable<U> | AsyncGenerator<U>): Promise<U[]> {
-    const out: U[] = [];
+  async toArray<U>(src: AsyncIterable<U | U[]> | AsyncGenerator<U | U[]>): Promise<U[]> {
+    const out: (U | U[])[] = [];
     for await (const el of src) {
       out.push(el);
     }
-    return out;
+    return castTo(out.flat());
   }
 }
 ```
@@ -345,16 +313,22 @@ export abstract class BaseModelSuite<T> {
 ## CLI - model:export
 The module provides the ability to generate an export of the model structure from all the various [@Model](https://github.com/travetto/travetto/tree/main/module/model/src/registry/decorator.ts#L14)s within the application.  This is useful for being able to generate the appropriate files to manually create the data schemas in production.
 
-**Terminal: Running model export**
+**Terminal: Help for model:export**
 ```bash
 $ trv model:export --help
 
 Usage: model:export [options] <provider:string> <models...:string>
 
+Description:
+  Export model definitions for a selected provider and model set.
+
+  The command resolves candidate models and delegates to provider-specific
+  export logic to produce schema/install artifacts.
+
 Options:
   -p, --profile <string>  Application profiles
   -m, --module <module>   Module to run for
-  -h, --help              display help for command
+  --help                  display help for command
 
 Providers
 --------------------
@@ -363,21 +337,29 @@ Providers
 Models
 --------------------
   * samplemodel
+
+Examples:
 ```
 
 ## CLI - model:install
 The module provides the ability to install all the various [@Model](https://github.com/travetto/travetto/tree/main/module/model/src/registry/decorator.ts#L14)s within the application given the current configuration being targeted.  This is useful for being able to prepare the datastore manually.
 
-**Terminal: Running model install**
+**Terminal: Help for model:install**
 ```bash
 $ trv model:install --help
 
 Usage: model:install [options] <provider:string> <models...:string>
 
+Description:
+  Install or update model definitions for a selected provider.
+
+  The command resolves candidate models and applies provider install/upsert
+  operations so backing stores are prepared for runtime usage.
+
 Options:
   -p, --profile <string>  Application profiles
   -m, --module <module>   Module to run for
-  -h, --help              display help for command
+  --help                  display help for command
 
 Providers
 --------------------
@@ -386,4 +368,6 @@ Providers
 Models
 --------------------
   * samplemodel
+
+Examples:
 ```

package/__index__.ts

@@ -8,7 +8,6 @@ export * from './src/types/basic.ts';
 export * from './src/types/blob.ts';
 export * from './src/types/bulk.ts';
 export * from './src/types/crud.ts';
-export * from './src/types/indexed.ts';
 export * from './src/types/expiry.ts';
 export * from './src/types/storage.ts';
 
@@ -16,7 +15,6 @@ export * from './src/util/blob.ts';
 export * from './src/util/bulk.ts';
 export * from './src/util/crud.ts';
 export * from './src/util/expiry.ts';
-export * from './src/util/indexed.ts';
 export * from './src/util/storage.ts';
 
 export * from './src/error/exists.ts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/model",
-  "version": "8.0.0-alpha.2",
+  "version": "8.0.0-alpha.21",
   "type": "module",
   "description": "Datastore abstraction for core operations.",
   "keywords": [
@@ -27,14 +27,14 @@
     "directory": "module/model"
   },
   "dependencies": {
-    "@travetto/config": "^8.0.0-alpha.2",
-    "@travetto/di": "^8.0.0-alpha.2",
-    "@travetto/registry": "^8.0.0-alpha.2",
-    "@travetto/schema": "^8.0.0-alpha.2"
+    "@travetto/config": "^8.0.0-alpha.20",
+    "@travetto/di": "^8.0.0-alpha.19",
+    "@travetto/registry": "^8.0.0-alpha.19",
+    "@travetto/schema": "^8.0.0-alpha.20"
   },
   "peerDependencies": {
-    "@travetto/cli": "^8.0.0-alpha.3",
-    "@travetto/test": "^8.0.0-alpha.2"
+    "@travetto/cli": "^8.0.0-alpha.26",
+    "@travetto/test": "^8.0.0-alpha.19"
   },
   "peerDependenciesMeta": {
     "@travetto/cli": {

package/src/error/invalid-index.ts

@@ -1,13 +1,13 @@
 import { type Class, RuntimeError } from '@travetto/runtime';
 
-import type { IndexConfig } from '../registry/types.ts';
 import type { ModelType } from '../types/model.ts';
+import type { IndexConfig } from '../registry/types.ts';
 
 /**
  * Represents when an index is invalid
  */
 export class IndexNotSupported<T extends ModelType> extends RuntimeError {
-  constructor(cls: Class<T>, idx: IndexConfig<T>, message: string = '') {
+  constructor(cls: Class<T>, idx: IndexConfig, message: string = '') {
     super(`${typeof cls === 'string' ? cls : cls.name} and index ${idx.name} of type ${idx.type} is not supported. ${message}`.trim(), { category: 'data' });
   }
 }

package/src/registry/decorator.ts

@@ -1,8 +1,8 @@
-import { RuntimeError, castTo, type Class, getClass } from '@travetto/runtime';
+import { castTo, type Class, getClass } from '@travetto/runtime';
 import { SchemaRegistryIndex } from '@travetto/schema';
 
 import type { ModelType } from '../types/model.ts';
-import type { DataHandler, IndexConfig, ModelConfig, PrePersistScope } from './types.ts';
+import type { DataHandler, ModelConfig, PrePersistScope } from './types.ts';
 import { ModelRegistryIndex } from './registry-index.ts';
 
 /**
@@ -24,19 +24,6 @@ export function Model(config: Partial<ModelConfig<ModelType>> | string = {}) {
   };
 }
 
-/**
- * Defines an index on a model
- * @kind decorator
- */
-export function Index<T extends ModelType>(...indices: IndexConfig<T>[]) {
-  if (indices.some(config => config.fields.some(field => field === 'id'))) {
-    throw new RuntimeError('Cannot create an index with the id field');
-  }
-  return function (cls: Class<T>): void {
-    ModelRegistryIndex.getForRegister(cls).register({ indices });
-  };
-}
-
 /**
  * Model field decorator for denoting expiry date/time
  * @augments `@travetto/schema:Field`
@@ -102,6 +89,19 @@ export function Transient<T>() {
   };
 }
 
+/**
+ * Prevent a field from being persisted
+ * @augments `@travetto/schema:Field`
+ * @kind decorator
+ */
+export function TransientField() {
+  return function <K extends string, C extends Partial<Record<K, unknown>>>(instance: C, property: K): void {
+    ModelRegistryIndex.getForRegister(getClass(instance)).register({
+      transientFields: [property]
+    });
+  };
+}
+
 /**
  * Model class decorator for post-load behavior
  * @augments `@travetto/schema:Schema`

package/src/registry/registry-adapter.ts

@@ -7,9 +7,10 @@ import type { ModelConfig } from './types.ts';
 function combineClasses(target: ModelConfig, sources: Partial<ModelConfig>[]): ModelConfig {
   for (const source of sources) {
     Object.assign(target, source, {
-      indices: [...(target.indices || []), ...(source.indices || [])],
+      indices: { ...(target.indices || {}), ...(source.indices || {}) },
       postLoad: [...(target.postLoad || []), ...(source.postLoad || [])],
       prePersist: [...(target.prePersist || []), ...(source.prePersist || [])],
+      transientFields: [...(target.transientFields || []), ...(source.transientFields || [])],
     });
   }
   if (target.store) {
@@ -29,11 +30,12 @@ export class ModelRegistryAdapter implements RegistryAdapter<ModelConfig> {
   register(...data: Partial<ModelConfig>[]): ModelConfig {
     const config = this.#config ??= {
       class: this.#cls,
-      indices: [],
+      indices: {},
       autoCreate: 'development',
       store: this.#cls.name,
       postLoad: [],
-      prePersist: []
+      prePersist: [],
+      transientFields: []
     };
     combineClasses(config, data);
     return config;
@@ -50,6 +52,7 @@ export class ModelRegistryAdapter implements RegistryAdapter<ModelConfig> {
 
       config.postLoad = [...parent.postLoad ?? [], ...config.postLoad ?? []];
       config.prePersist = [...parent.prePersist ?? [], ...config.prePersist ?? []];
+      config.transientFields = [...parent.transientFields ?? [], ...config.transientFields ?? []];
     }
   }
 

package/src/registry/registry-index.ts

@@ -2,13 +2,9 @@ import { type RegistryIndex, RegistryIndexStore, Registry } from '@travetto/regi
 import { RuntimeError, castTo, type Class } from '@travetto/runtime';
 import { SchemaRegistryIndex } from '@travetto/schema';
 
-import type { IndexConfig, IndexType, ModelConfig } from './types.ts';
+import type { IndexConfig, ModelConfig } from './types.ts';
 import type { ModelType } from '../types/model.ts';
 import { ModelRegistryAdapter } from './registry-adapter.ts';
-import { IndexNotSupported } from '../error/invalid-index.ts';
-import { NotFoundError } from '../error/not-found.ts';
-
-type IndexResult<T extends ModelType, K extends IndexType[]> = IndexConfig<T> & { type: K[number] };
 
 /**
  * Model registry index for managing model configurations across classes
@@ -33,12 +29,8 @@ export class ModelRegistryIndex implements RegistryIndex {
     return this.#instance.getStoreName(cls);
   }
 
-  static getIndices<T extends ModelType, K extends IndexType[]>(cls: Class<T>, supportedTypes?: K): IndexResult<T, K>[] {
-    return this.#instance.getIndices(cls, supportedTypes);
-  }
-
-  static getIndex<T extends ModelType, K extends IndexType[]>(cls: Class<T>, name: string, supportedTypes?: K): IndexResult<T, K> {
-    return this.#instance.getIndex(cls, name, supportedTypes);
+  static getIndices<T extends ModelType>(cls: Class<T>): IndexConfig[] {
+    return this.#instance.getIndices(cls);
   }
 
   static getExpiryFieldName<T extends ModelType>(cls: Class<T>): keyof T {
@@ -94,25 +86,11 @@ export class ModelRegistryIndex implements RegistryIndex {
     return this.store.get(cls).get().store;
   }
 
-  /**
-   * Get Index
-   */
-  getIndex<T extends ModelType, K extends IndexType[]>(cls: Class<T>, name: string, supportedTypes?: K): IndexResult<T, K> {
-    const config = this.getConfig(cls).indices?.find((idx): idx is IndexConfig<T> => idx.name === name);
-    if (!config) {
-      throw new NotFoundError(`${cls.name} Index`, `${name}`);
-    }
-    if (supportedTypes && !supportedTypes.includes(config.type)) {
-      throw new IndexNotSupported(cls, config, `${config.type} indices are not supported.`);
-    }
-    return config;
-  }
-
   /**
    * Get Indices
    */
-  getIndices<T extends ModelType, K extends IndexType[]>(cls: Class<T>, supportedTypes?: K): IndexResult<T, K>[] {
-    return (this.getConfig(cls).indices ?? []).filter((idx): idx is IndexConfig<T> => !supportedTypes || supportedTypes.includes(idx.type));
+  getIndices<T extends ModelType>(cls: Class<T>): IndexConfig[] {
+    return Object.values(this.getConfig(cls).indices ?? []);
   }
 
   /**

package/src/registry/types.ts

@@ -1,23 +1,29 @@
-import type { Class, Primitive, ValidFields } from '@travetto/runtime';
+import type { Class } from '@travetto/runtime';
 
 import type { ModelType } from '../types/model.ts';
 
-type RetainPrimitiveFields<T> = Pick<T, ValidFields<T, Primitive | Date>>;
-
-export type SortClauseRaw<T> = {
-  [P in keyof T]?:
-  T[P] extends object ? SortClauseRaw<RetainPrimitiveFields<T[P]>> : 1 | -1;
-};
-
-type IndexClauseRaw<T> = {
-  [P in keyof T]?:
-  T[P] extends object ? IndexClauseRaw<RetainPrimitiveFields<T[P]>> : 1 | -1 | true;
-};
-
 export type DataHandler<T = unknown> = (inst: T) => (Promise<T | void> | T | void);
 
 export type PrePersistScope = 'full' | 'partial' | 'all';
 
+/**
+ * Index options
+ */
+export type IndexConfig<V extends string = string> = {
+  /**
+   * Index name
+   */
+  name: string;
+  /**
+   * Type
+   */
+  type: V;
+  /**
+   * Class the index belongs to
+   */
+  class: Class<ModelType>;
+};
+
 /**
  * Model config
  */
@@ -33,7 +39,7 @@ export class ModelConfig<T extends ModelType = ModelType> {
   /**
    * Indices
    */
-  indices?: IndexConfig<T>[];
+  indices?: Record<string, IndexConfig>;
   /**
    * Vendor specific extras
    */
@@ -54,29 +60,8 @@ export class ModelConfig<T extends ModelType = ModelType> {
    * Post-load handlers
    */
   postLoad?: DataHandler<unknown>[];
-}
-
-/**
- * Supported index types
- */
-export type IndexType = 'unique' | 'unsorted' | 'sorted';
-
-/**
- * Index options
- */
-export type IndexConfig<T extends ModelType> = {
   /**
-   * Index name
+   * Fields to ignore during persistence
    */
-  name: string;
-  /**
-   * Fields and sort order
-   */
-  fields: IndexClauseRaw<RetainPrimitiveFields<T>>[];
-  /**
-   * Type
-   */
-  type: IndexType;
-};
-
-export type IndexField<T extends ModelType> = IndexClauseRaw<RetainPrimitiveFields<T>>;
+  transientFields?: string[];
+}

package/src/types/basic.ts

@@ -1,5 +1,5 @@
 import type { Class } from '@travetto/runtime';
-import type { ModelIdSource, ModelType, OptionalId } from '../types/model.ts';
+import type { ModelIdSource, ModelType, OptionalId } from './model.ts';
 
 /**
  * Interface for basic data interface

package/src/types/blob.ts

@@ -42,12 +42,13 @@ export interface ModelBlobSupport {
   updateBlobMetadata(location: string, metadata: BinaryMetadata): Promise<void>;
 
   /**
-   * Produces an externally usable URL for sharing limited read access to a specific resource
+   * Produces an externally usable URL for sharing limited read access to a specific resource.
+   * If expiresIn is explicitly set to false, returns a direct/public URL.
    *
    * @param location The asset location to read from
-   * @param expiresIn Expiry
+   * @param expiresIn Expiry or false for public/direct URL
    */
-  getBlobReadUrl?(location: string, expiresIn?: TimeSpan): Promise<string>;
+  getBlobReadUrl?(location: string, expiresIn?: TimeSpan | false): Promise<string>;
 
   /**
    * Produces an externally usable URL for sharing allowing direct write access

package/src/types/bulk.ts

@@ -2,7 +2,7 @@ import { type Class, RuntimeError } from '@travetto/runtime';
 import type { ValidationError, ValidationResultError } from '@travetto/schema';
 
 import type { ModelCrudSupport } from './crud.ts';
-import type { ModelType, OptionalId } from '../types/model.ts';
+import type { ModelType, OptionalId } from './model.ts';
 
 /**
  * Bulk operation. Each operation has a single action and payload

package/src/types/crud.ts

@@ -1,6 +1,6 @@
 import type { Class } from '@travetto/runtime';
 
-import type { ModelType, OptionalId } from '../types/model.ts';
+import type { ModelListOptions, ModelType, OptionalId } from './model.ts';
 
 import type { ModelBasicSupport } from './basic.ts';
 
@@ -38,7 +38,12 @@ export interface ModelCrudSupport extends ModelBasicSupport {
   updatePartial<T extends ModelType>(cls: Class<T>, item: Partial<T> & { id: string }, view?: string): Promise<T>;
 
   /**
-   * List all items
+   * List all items of a collection, results returned in batches of items.
+   *
+   * Note: Batch size hint can be used to optimize batch size, but is not guaranteed.
+   *
+   * @param cls The class to list
+   * @param options Options for listing
    */
-  list<T extends ModelType>(cls: Class<T>): AsyncIterable<T>;
+  list<T extends ModelType>(cls: Class<T>, options?: ModelListOptions): AsyncIterable<T[]>;
 }

package/src/types/expiry.ts

@@ -1,6 +1,6 @@
 import type { Class } from '@travetto/runtime';
 
-import type { ModelType } from '../types/model.ts';
+import type { ModelType } from './model.ts';
 import type { ModelCrudSupport } from './crud.ts';
 
 /**

package/src/types/model.ts

@@ -16,4 +16,13 @@ export interface ModelType {
   id: string;
 }
 
-export type OptionalId<T extends ModelType> = Omit<T, 'id'> & { id?: string };
+export type OptionalId<T extends ModelType> = Omit<T, 'id'> & { id?: string };
+
+/**
+ * Options for listing items
+ */
+export interface ModelListOptions {
+  abort?: AbortSignal;
+  limit?: number;
+  batchSizeHint?: number;
+}

package/src/types/storage.ts

@@ -1,6 +1,6 @@
 import type { Class } from '@travetto/runtime';
 
-import type { ModelType } from '../types/model.ts';
+import type { ModelType } from './model.ts';
 
 /**
  * This interface defines the behavior for dealing with the