Interface KosContainerAwareOptions<T>

Configuration options for the

Kos Container Aware

decorator.

interface KosContainerAwareOptions<T> {
    containerProperty?: string;
    includeMethods?: boolean;
    includeGetters?: boolean;
    containerOptions?: {
        sortKey?: keyof T;
        indexMap?: Record<string, keyof T | ((model) => MaybePromise<undefined | string | string[]>)>;
        parentId?: string;
        extensionId?: string;
        maxCapacity?: number;
        evictionStrategy?: "fifo" | "lru" | "custom";
        evictionBatchSize?: number;
        customEvictionFilter?: ((models) => T[]);
    };
    modelsProperty?: string;
    legacy?: boolean;
}

Type Parameters

  • T extends IKosDataModel = IKosDataModel

    The type of models contained in the container (must extend IKosDataModel)

Properties

containerProperty? includeMethods? includeGetters? containerOptions? modelsProperty? legacy?

Properties

Optional containerProperty

containerProperty?: string

Container property name on the model instance.

Default

"container"

Example

@kosContainerAware({ containerProperty: "devices" })
class DeviceContainer {
  // Access via: this.devices.addModel(...)
}

Optional includeMethods

includeMethods?: boolean

Whether to include convenience methods (getModel, addModel, removeModel, addAll, removeAll, removeAndDestroy, removeAndDestroyAll).

Default

true

Example

@kosContainerAware({ includeMethods: false })
class Container {
  // Only this.container property available, no convenience methods
}

Optional includeGetters

includeGetters?: boolean

Whether to include reactive getters (models, data).

Default

true

Example

@kosContainerAware({ includeGetters: false })
class Container {
  // No this.models or this.data getters, use this.container.data directly
}

Optional containerOptions

containerOptions?: {
    sortKey?: keyof T;
    indexMap?: Record<string, keyof T | ((model) => MaybePromise<undefined | string | string[]>)>;
    parentId?: string;
    extensionId?: string;
    maxCapacity?: number;
    evictionStrategy?: "fifo" | "lru" | "custom";
    evictionBatchSize?: number;
    customEvictionFilter?: ((models) => T[]);
}

Container-specific configuration options passed to KosModelContainer constructor.

Type declaration

  • Optional sortKey?: keyof T

    Default property to sort models by

  • Optional indexMap?: Record<string, keyof T | ((model) => MaybePromise<undefined | string | string[]>)>

    Index mapping for efficient queries. Keys are index names, values are either:

    • Property names (string keys) for simple property-based indexing
    • Functions that return index keys for complex logic

    Example

    indexMap: {
      byStatus: "connectionStatus",                    // Property-based
      byType: (device) => device.type.toLowerCase(),  // Function-based
      needsUpdate: (device) => device.version < "2.0" // Boolean logic
    }
  • Optional parentId?: string

    Parent model ID for the container. If not provided, automatically uses the modelId parameter from the model's constructor.

    Default

    Inferred from constructor modelId parameter
  • Optional extensionId?: string

    Extension identifier for the container

  • Optional maxCapacity?: number

    SAFETY NET: Maximum number of models this container can hold. When exceeded, models are automatically evicted and destroyed based on evictionStrategy.

    Primary use case: Prevent memory overflow when cleanup handlers are missing or data becomes inconsistent. Set higher than normal usage to catch edge cases.

    Example

    containerOptions: {
      maxCapacity: 10000,  // Safety net: expect ~100-1000 normally
      evictionStrategy: 'fifo'
    }
  • Optional evictionStrategy?: "fifo" | "lru" | "custom"

    Strategy for selecting which models to evict when maxCapacity is exceeded.

    • fifo (default): Remove oldest models first - best for event streams, logs
    • lru: Remove least recently accessed models - best for caches
    • custom: Use customEvictionFilter to determine eviction candidates

    Default

    'fifo'
  • Optional evictionBatchSize?: number

    Number of models to evict when maxCapacity is exceeded.

    Default

    Math.max(10, Math.ceil(maxCapacity * 0.1))
  • Optional customEvictionFilter?: ((models) => T[])

    Custom filter function for 'custom' eviction strategy. Should return models that are candidates for eviction.

    Example

    customEvictionFilter: (models) => {
      return models.filter(m =>
        m.status === 'resolved' &&
        Date.now() - m.resolvedAt > 3600000
      );
    }
      • (models): T[]

      • Parameters

        • models: T[]

        Returns T[]

Example

@kosContainerAware({
  containerOptions: {
    sortKey: "name",
    indexMap: {
      byType: "deviceType",
      active: (device) => device.isOnline
    },
    parentId: "custom-parent", // Overrides automatic inference
    extensionId: "device-manager",
    maxCapacity: 1000,  // Safety net for unbounded growth
    evictionStrategy: "fifo"
  }
})

Optional modelsProperty

modelsProperty?: string

Custom name for the reactive models array getter.

Default

"models"

Example

@kosContainerAware({ modelsProperty: "items" })
class Container {
  get items() { return this.container.data; } // Instead of 'models'
}

Optional legacy

legacy?: boolean

Legacy compatibility mode. Uses '_models' as the container property name instead of 'container' for backward compatibility with existing code.

Default

false

Deprecated

Use containerProperty instead for new code

Settings

Member Visibility

Theme

On This Page

containerPropertyincludeMethodsincludeGetterscontainerOptionsmodelsPropertylegacy