Function kosContainerAware

Class decorator that automatically adds container management capabilities to a KOS model.

This decorator eliminates the need for manual container setup by:

• Adding a container property (default: container) for managing model collections
• Adding convenience methods (getModel, addModel, removeModel, addAll, removeAll, removeAndDestroy, removeAndDestroyAll) if includeMethods is true (default)
• Adding reactive getters (models, data) if includeGetters is true (default)
• Automatically inferring parentId from the model's constructor modelId parameter
• Registering container as @kosChild for proper lifecycle management and cleanup
• Supporting custom indexing via containerOptions.indexMap for efficient queries

Automatic Hierarchy Integration

The decorator automatically registers the container as a @kosChild, ensuring:

• Proper lifecycle management (init, load, destroy)
• Automatic cleanup when parent model is destroyed
• Participation in the KOS reactive system
• Memory management and observer disposal

TypeScript Usage

IMPORTANT: Use TypeScript interface merging to get proper type information:

interface MyContainerModelImpl extends KosContainerAware<MyItemModel> {}

@kosContainerAware<MyItemModel>()
class MyContainerModelImpl implements IKosDataModel {
  // All container properties are now available with full type safety
}
Copy

Model Lifecycle: removeModel vs removeAndDestroy

The decorator provides both removal and destruction methods with different purposes:

removeModel(id) / removeAll(ids) - Removes from container WITHOUT destroying:

• Use when moving models between containers
• Use when temporarily hiding models that may be re-added
• Use when model lifecycle is managed elsewhere
• Container handles cleanup of observers and metadata
• Model remains in memory and can be used elsewhere

removeAndDestroy(id) / removeAndDestroyAll(ids) - Removes AND destroys:

• Use when permanently removing models from the system
• Use when models should be fully cleaned up and disposed
• Calls destroyKosModel() automatically after removal
• Ensures proper cleanup of all model resources
• Model is removed from framework and memory

// Example: Explicit lifecycle control
@kosTopicHandler({ topic: "/device/sensor/removed" })
handleSensorRemoved(id: string) {
  // Permanently remove - sensor is gone from system
  await this.removeAndDestroy(id);
}

// Example: Reorganization without destruction
moveSensorToArchive(id: string) {
  const sensor = this.getModel(id);
  if (sensor) {
    this.removeModel(id);           // Remove from active container
    this.archive.addModel(sensor);  // Add to archive container
  }
}
Copy

Configuration Options

@kosContainerAware<UserModel>({
  containerProperty: "users",        // Custom property name (default: "container")
  includeMethods: true,              // Include convenience methods (default: true)
  includeGetters: true,              // Include reactive getters (default: true)
  modelsProperty: "userList",        // Custom models getter name (default: "models")
  legacy: false,                     // Use "_models" property name (default: false)
  containerOptions: {
    parentId: "custom-parent",       // Override automatic parentId inference
    sortKey: "name",                 // Default sorting key
    extensionId: "my-extension",     // Extension identifier
    indexMap: {                      // Automatic indexing for efficient queries
      byRole: "role",                // Property-based index
      byStatus: (user) => user.active ? "active" : "inactive", // Function-based index
      admins: (user) => user.role === "admin" // Boolean index
    }
  }
})
Copy

See

• KosContainerAware - Interface for TypeScript merging
• KosContainerAwareOptions - Configuration options interface

Example

// Minimal configuration - parentId automatically inferred
interface ItemContainerModelImpl extends KosContainerAware<ItemModel> {}

@kosContainerAware<ItemModel>()
class ItemContainerModelImpl implements IKosDataModel {
  id: string;

  constructor(modelId: string, options: ContainerOptions, context: KosCreationContext) {
    this.id = modelId;
    // Container automatically created with parentId: modelId
  }
}

// With index configuration
interface UserContainerModelImpl extends KosContainerAware<UserModel> {}

@kosContainerAware<UserModel>({
  containerOptions: {
    indexMap: {
      byRole: "role",
      byStatus: (user) => user.status
    }
  }
})
class UserContainerModelImpl implements IKosDataModel {
  constructor(modelId: string, options: ContainerOptions, context: KosCreationContext) {
    this.id = modelId;
  }
}

// Legacy mode for backward compatibility
interface LegacyContainerModelImpl extends KosContainerAware<LegacyModel> {}

@kosContainerAware<LegacyModel>({
  legacy: true,  // Uses '_models' as property name
  containerOptions: {
    sortKey: "name"
  }
})
class LegacyContainerModelImpl implements IKosDataModel {
  // Container available as this._models for backward compatibility
}
Copy

Since

2.1.0