@awesome-ecs/abstract 0.21.0 → 0.21.1

package/dist/identity-component-BDWEtAXA.d.cts

@@ -0,0 +1,238 @@
+import { BooleanProps, Immutable } from "./types-DvzdpbLu.cjs";
+
+//#region src/components/component.d.ts
+type ComponentTypeUid = string | number;
+/**
+ * The `IComponent` interface provides the main storage mechanism of `IEntity` state, and can be accessed and modified by `Systems`.
+ *
+ * The `IComponent` implementations should not contain any logic methods, apart from quick-access functionality.
+ */
+interface IComponent {
+  /**
+   * The `ComponentTypeUid` is a unique identifier for each Component type.
+   * @type {ComponentTypeUid}
+   */
+  readonly componentType: ComponentTypeUid;
+  /**
+   * Specifies whether the Component state should be serialized as part of an `IEntitySnapshot`.
+   * This is useful if the state needs to be replicated or updated through remote updates (e.g., coming from the server or peers).
+   * @type {boolean}
+   */
+  readonly isSerializable: boolean;
+  /**
+   * @optional
+   * Specifies the current version of the component.
+   * This is useful for keeping backwards-compatibility when the stored state might be of a different version.
+   * @type {number}
+   */
+  readonly version?: number;
+  /**
+   * @optional
+   * The custom serialization function of this Component, used to transfer it into a Snapshot, or used for logging the Component stored state.
+   * If not provided, the standard `JSON.stringify()` functionality applies.
+   * @returns {string | object} The serialized form of the Component.
+   */
+  toJSON?(): string | object;
+  /**
+   * Allows for custom logic when loading the current from an `IEntitySnapshot`.
+   * The default behavior simply overwrites the fields with the target state.
+   * @param {this} targetState The target state to load from.
+   */
+  load?(targetState: this): void;
+}
+//#endregion
+//#region src/entities/entity-proxies.d.ts
+/**
+ * The `IEntityProxy` represents a pointer to another `Entity`.
+ */
+interface IEntityProxy {
+  /**
+   * The type of the entity that the proxy points to.
+   */
+  readonly entityType: EntityTypeUid;
+  /**
+   * The unique identifier of the entity that the proxy points to.
+   */
+  readonly entityUid: EntityUid;
+}
+/**
+ * A utility extension of `IEntityProxy`.
+ * Useful for providing strong `Type` information when using the IEntityProxy.
+ *
+ * @template TEntity - The type of the entity that the proxy points to.
+ */
+interface EntityProxy<TEntity extends IEntity> extends IEntityProxy {}
+/**
+ * A helper type to create a typed entity proxy.
+ */
+type TypedEntityProxy<T extends EntityTypeUid> = {
+  entityType: T;
+  entityUid: EntityUid;
+};
+/**
+ * A mapped type that transforms an array of EntityType into an array of TypedEntityProxy.
+ */
+type RequiredProxies<TProxyTypes extends readonly EntityTypeUid[]> = [...{ [I in keyof TProxyTypes]: TypedEntityProxy<TProxyTypes[I]> }, ...IEntityProxy[]];
+/**
+ * A repository for managing entity-to-entity relationships (proxies).
+ * This centralized repository is the single source of truth for all proxy data.
+ */
+interface IEntityProxyRepository {
+  /**
+   * Registers a bi-directional proxy relationship between a source and a target.
+   * @param source - The proxy of the source entity.
+   * @param target - The proxy of the target entity.
+   * @param cleanup - If true, any existing proxies of the same type on the source and target will be removed before registering the new one.
+   */
+  register(source: IEntityProxy, target: IEntityProxy, cleanup?: boolean): void;
+  /**
+   * Registers multiple bi-directional proxy relationships for a source entity.
+   * @param source - The proxy of the source entity.
+   * @param targets - The proxies of the target entities.
+   * @param cleanup - If true, any existing proxies of the same types as the new targets will be removed from the source before registering.
+   */
+  registerMany(source: IEntityProxy, targets: readonly IEntityProxy[], cleanup?: boolean): void;
+  /**
+   * Removes a bi-directional proxy relationship between a source and a target.
+   * @param source - The proxy of the source entity.
+   * @param target - The proxy of the target entity.
+   */
+  remove(source: IEntityProxy, target: IEntityProxy): void;
+  /**
+   * Removes all proxies from a source entity, optionally filtered by the target entity type.
+   * This will also remove the corresponding back-references from the target entities.
+   * @param source - The proxy of the source entity.
+   * @param targetType - The optional entity type of the targets to remove. If not provided, all proxies for the source are removed.
+   */
+  removeAllFor(source: IEntityProxy, targetType?: EntityTypeUid): void;
+  /**
+   * Retrieves a single proxy of a specific type for a source entity.
+   * If multiple proxies of the same type exist, it returns the first one found.
+   * @param source - The proxy of the source entity.
+   * @param targetType - The entity type of the target proxy to retrieve.
+   * @returns The entity proxy, or null if not found.
+   */
+  get(source: IEntityProxy, targetType: EntityTypeUid): IEntityProxy | null;
+  /**
+   * Retrieves all proxies of a specific type for a source entity.
+   * @param source - The proxy of the source entity.
+   * @param targetType - The entity type of the target proxies to retrieve.
+   * @returns A readonly array of entity proxies.
+   */
+  getMany(source: IEntityProxy, targetType: EntityTypeUid): Readonly<IEntityProxy[]>;
+  /**
+   * Retrieves all proxies for a source entity.
+   * @param source - The proxy of the source entity.
+   * @returns A readonly map of entity type UIDs to an array of their proxies.
+   */
+  getAll(source: IEntityProxy): ReadonlyMap<EntityTypeUid, Readonly<IEntityProxy[]>>;
+}
+//#endregion
+//#region src/entities/entity.d.ts
+/**
+ * Represents the unique identifier for an entity type.
+ * Can be either a string or a number.
+ */
+type EntityTypeUid = string | number;
+/**
+ * Represents the unique identifier for an entity.
+ * Can be either a string or a number.
+ */
+type EntityUid = string | number;
+/**
+ * The `IEntityModel` represents the basic identity information about the current `IEntity`.
+ * It's mandatory for each Entity, and it contains the minimal-required information needed for instantiating the Entity.
+ *
+ * The Features property can be used to toggle Entity features on and off.
+ *
+ * @template TFeatures - A type that extends `BooleanProps<TFeatures>` to represent the features of the entity.
+ *                      Defaults to `unknown` if not provided.
+ */
+interface IEntityModel {
+  /**
+   * The unique identifier of the entity.
+   */
+  readonly uid: EntityUid;
+  /**
+   * Optional proxies of the entity.
+   */
+  readonly proxies?: readonly IEntityProxy[];
+}
+/**
+ * Base interface for entity models that require feature flags.
+ * @template TFeatures - A type that extends `BooleanProps<TFeatures>` to represent the features of the entity.
+ */
+interface IEntityModelWithFeatures<TFeatures extends BooleanProps<TFeatures> = unknown> extends IEntityModel {
+  readonly features: TFeatures;
+}
+/**
+ * Base interface for entity models that require specific proxies.
+ * @template TProxyTypes An array of EntityType that are required as proxies.
+ */
+interface IEntityModelWithRequiredProxies<TProxyTypes extends readonly EntityTypeUid[]> extends Omit<IEntityModel, 'proxies'> {
+  readonly proxies: RequiredProxies<TProxyTypes>;
+}
+/**
+ * The `IEntity` interface represents a container of Components and Entity Proxies.
+ * It is designed to be immutable and only modifiable through System operations.
+ *
+ * Implementations of `IEntity` can contain quick-access methods for `Components` or `Proxies`,
+ * but should not contain any state-changing logic apart from quick-access functionality.
+ */
+interface IEntity {
+  /**
+   * A Map of Components associated with this Entity.
+   * The keys are ComponentTypeUid, and the values are IComponent instances.
+   */
+  readonly components: ReadonlyMap<ComponentTypeUid, IComponent>;
+  /**
+   * The IdentityComponent represents mandatory state any Entity needs to have.
+   * It is a readonly reference to an IdentityComponent instance, which contains the minimal-required information
+   * needed for instantiating the Entity.
+   */
+  readonly identity: Readonly<IdentityComponent<IEntityModel>>;
+  /**
+   * A reference to the own Proxy of this Entity.
+   * It is a readonly reference to an IEntityProxy instance, which points to this Entity.
+   * This is useful for quick access of Proxy data.
+   */
+  readonly myProxy: Readonly<EntityProxy<this>>;
+}
+//#endregion
+//#region src/components/identity-component.d.ts
+/**
+ * The `BasicComponentType` enum defines the types of basic components available.
+ */
+declare enum BasicComponentType {
+  identity = "identity",
+}
+/**
+ * IdentityComponent interface represents the basic information regarding what makes the current Entity unique.
+ * It extends the IComponent interface.
+ *
+ * @template TModel - The type of the model that extends IEntityModel.
+ */
+interface IdentityComponent<TModel extends IEntityModel> extends IComponent {
+  /**
+   * The Entity Type that defines what Category type the Entity is part of.
+   * There can be multiple Entities sharing the same EntityType.
+   */
+  readonly entityType: EntityTypeUid;
+  /**
+   * The Model is the basic information needed to create an `IEntity` when it's first initialized.
+   * It provides a first snapshot of information needed for the successful creation of an Entity instance.
+   *
+   * @type {Immutable<TModel>}
+   */
+  readonly model: Immutable<TModel>;
+  /**
+   * Keeps track when the Entity's systems have ran last.
+   * Useful to calculate the `DeltaTime` between runs.
+   *
+   * @type {Date | undefined}
+   */
+  readonly lastUpdated?: Date;
+}
+//#endregion
+export { BasicComponentType, ComponentTypeUid, EntityProxy, EntityTypeUid, EntityUid, IComponent, IEntity, IEntityModel, IEntityModelWithFeatures, IEntityModelWithRequiredProxies, IEntityProxy, IEntityProxyRepository, IdentityComponent, RequiredProxies, TypedEntityProxy };
+//# sourceMappingURL=identity-component-BDWEtAXA.d.cts.map

package/dist/identity-component-CR1ULadR.d.ts

@@ -0,0 +1,238 @@
+import { BooleanProps, Immutable } from "./types-yh4pOGEm.js";
+
+//#region src/components/component.d.ts
+type ComponentTypeUid = string | number;
+/**
+ * The `IComponent` interface provides the main storage mechanism of `IEntity` state, and can be accessed and modified by `Systems`.
+ *
+ * The `IComponent` implementations should not contain any logic methods, apart from quick-access functionality.
+ */
+interface IComponent {
+  /**
+   * The `ComponentTypeUid` is a unique identifier for each Component type.
+   * @type {ComponentTypeUid}
+   */
+  readonly componentType: ComponentTypeUid;
+  /**
+   * Specifies whether the Component state should be serialized as part of an `IEntitySnapshot`.
+   * This is useful if the state needs to be replicated or updated through remote updates (e.g., coming from the server or peers).
+   * @type {boolean}
+   */
+  readonly isSerializable: boolean;
+  /**
+   * @optional
+   * Specifies the current version of the component.
+   * This is useful for keeping backwards-compatibility when the stored state might be of a different version.
+   * @type {number}
+   */
+  readonly version?: number;
+  /**
+   * @optional
+   * The custom serialization function of this Component, used to transfer it into a Snapshot, or used for logging the Component stored state.
+   * If not provided, the standard `JSON.stringify()` functionality applies.
+   * @returns {string | object} The serialized form of the Component.
+   */
+  toJSON?(): string | object;
+  /**
+   * Allows for custom logic when loading the current from an `IEntitySnapshot`.
+   * The default behavior simply overwrites the fields with the target state.
+   * @param {this} targetState The target state to load from.
+   */
+  load?(targetState: this): void;
+}
+//#endregion
+//#region src/entities/entity-proxies.d.ts
+/**
+ * The `IEntityProxy` represents a pointer to another `Entity`.
+ */
+interface IEntityProxy {
+  /**
+   * The type of the entity that the proxy points to.
+   */
+  readonly entityType: EntityTypeUid;
+  /**
+   * The unique identifier of the entity that the proxy points to.
+   */
+  readonly entityUid: EntityUid;
+}
+/**
+ * A utility extension of `IEntityProxy`.
+ * Useful for providing strong `Type` information when using the IEntityProxy.
+ *
+ * @template TEntity - The type of the entity that the proxy points to.
+ */
+interface EntityProxy<TEntity extends IEntity> extends IEntityProxy {}
+/**
+ * A helper type to create a typed entity proxy.
+ */
+type TypedEntityProxy<T extends EntityTypeUid> = {
+  entityType: T;
+  entityUid: EntityUid;
+};
+/**
+ * A mapped type that transforms an array of EntityType into an array of TypedEntityProxy.
+ */
+type RequiredProxies<TProxyTypes extends readonly EntityTypeUid[]> = [...{ [I in keyof TProxyTypes]: TypedEntityProxy<TProxyTypes[I]> }, ...IEntityProxy[]];
+/**
+ * A repository for managing entity-to-entity relationships (proxies).
+ * This centralized repository is the single source of truth for all proxy data.
+ */
+interface IEntityProxyRepository {
+  /**
+   * Registers a bi-directional proxy relationship between a source and a target.
+   * @param source - The proxy of the source entity.
+   * @param target - The proxy of the target entity.
+   * @param cleanup - If true, any existing proxies of the same type on the source and target will be removed before registering the new one.
+   */
+  register(source: IEntityProxy, target: IEntityProxy, cleanup?: boolean): void;
+  /**
+   * Registers multiple bi-directional proxy relationships for a source entity.
+   * @param source - The proxy of the source entity.
+   * @param targets - The proxies of the target entities.
+   * @param cleanup - If true, any existing proxies of the same types as the new targets will be removed from the source before registering.
+   */
+  registerMany(source: IEntityProxy, targets: readonly IEntityProxy[], cleanup?: boolean): void;
+  /**
+   * Removes a bi-directional proxy relationship between a source and a target.
+   * @param source - The proxy of the source entity.
+   * @param target - The proxy of the target entity.
+   */
+  remove(source: IEntityProxy, target: IEntityProxy): void;
+  /**
+   * Removes all proxies from a source entity, optionally filtered by the target entity type.
+   * This will also remove the corresponding back-references from the target entities.
+   * @param source - The proxy of the source entity.
+   * @param targetType - The optional entity type of the targets to remove. If not provided, all proxies for the source are removed.
+   */
+  removeAllFor(source: IEntityProxy, targetType?: EntityTypeUid): void;
+  /**
+   * Retrieves a single proxy of a specific type for a source entity.
+   * If multiple proxies of the same type exist, it returns the first one found.
+   * @param source - The proxy of the source entity.
+   * @param targetType - The entity type of the target proxy to retrieve.
+   * @returns The entity proxy, or null if not found.
+   */
+  get(source: IEntityProxy, targetType: EntityTypeUid): IEntityProxy | null;
+  /**
+   * Retrieves all proxies of a specific type for a source entity.
+   * @param source - The proxy of the source entity.
+   * @param targetType - The entity type of the target proxies to retrieve.
+   * @returns A readonly array of entity proxies.
+   */
+  getMany(source: IEntityProxy, targetType: EntityTypeUid): Readonly<IEntityProxy[]>;
+  /**
+   * Retrieves all proxies for a source entity.
+   * @param source - The proxy of the source entity.
+   * @returns A readonly map of entity type UIDs to an array of their proxies.
+   */
+  getAll(source: IEntityProxy): ReadonlyMap<EntityTypeUid, Readonly<IEntityProxy[]>>;
+}
+//#endregion
+//#region src/entities/entity.d.ts
+/**
+ * Represents the unique identifier for an entity type.
+ * Can be either a string or a number.
+ */
+type EntityTypeUid = string | number;
+/**
+ * Represents the unique identifier for an entity.
+ * Can be either a string or a number.
+ */
+type EntityUid = string | number;
+/**
+ * The `IEntityModel` represents the basic identity information about the current `IEntity`.
+ * It's mandatory for each Entity, and it contains the minimal-required information needed for instantiating the Entity.
+ *
+ * The Features property can be used to toggle Entity features on and off.
+ *
+ * @template TFeatures - A type that extends `BooleanProps<TFeatures>` to represent the features of the entity.
+ *                      Defaults to `unknown` if not provided.
+ */
+interface IEntityModel {
+  /**
+   * The unique identifier of the entity.
+   */
+  readonly uid: EntityUid;
+  /**
+   * Optional proxies of the entity.
+   */
+  readonly proxies?: readonly IEntityProxy[];
+}
+/**
+ * Base interface for entity models that require feature flags.
+ * @template TFeatures - A type that extends `BooleanProps<TFeatures>` to represent the features of the entity.
+ */
+interface IEntityModelWithFeatures<TFeatures extends BooleanProps<TFeatures> = unknown> extends IEntityModel {
+  readonly features: TFeatures;
+}
+/**
+ * Base interface for entity models that require specific proxies.
+ * @template TProxyTypes An array of EntityType that are required as proxies.
+ */
+interface IEntityModelWithRequiredProxies<TProxyTypes extends readonly EntityTypeUid[]> extends Omit<IEntityModel, 'proxies'> {
+  readonly proxies: RequiredProxies<TProxyTypes>;
+}
+/**
+ * The `IEntity` interface represents a container of Components and Entity Proxies.
+ * It is designed to be immutable and only modifiable through System operations.
+ *
+ * Implementations of `IEntity` can contain quick-access methods for `Components` or `Proxies`,
+ * but should not contain any state-changing logic apart from quick-access functionality.
+ */
+interface IEntity {
+  /**
+   * A Map of Components associated with this Entity.
+   * The keys are ComponentTypeUid, and the values are IComponent instances.
+   */
+  readonly components: ReadonlyMap<ComponentTypeUid, IComponent>;
+  /**
+   * The IdentityComponent represents mandatory state any Entity needs to have.
+   * It is a readonly reference to an IdentityComponent instance, which contains the minimal-required information
+   * needed for instantiating the Entity.
+   */
+  readonly identity: Readonly<IdentityComponent<IEntityModel>>;
+  /**
+   * A reference to the own Proxy of this Entity.
+   * It is a readonly reference to an IEntityProxy instance, which points to this Entity.
+   * This is useful for quick access of Proxy data.
+   */
+  readonly myProxy: Readonly<EntityProxy<this>>;
+}
+//#endregion
+//#region src/components/identity-component.d.ts
+/**
+ * The `BasicComponentType` enum defines the types of basic components available.
+ */
+declare enum BasicComponentType {
+  identity = "identity",
+}
+/**
+ * IdentityComponent interface represents the basic information regarding what makes the current Entity unique.
+ * It extends the IComponent interface.
+ *
+ * @template TModel - The type of the model that extends IEntityModel.
+ */
+interface IdentityComponent<TModel extends IEntityModel> extends IComponent {
+  /**
+   * The Entity Type that defines what Category type the Entity is part of.
+   * There can be multiple Entities sharing the same EntityType.
+   */
+  readonly entityType: EntityTypeUid;
+  /**
+   * The Model is the basic information needed to create an `IEntity` when it's first initialized.
+   * It provides a first snapshot of information needed for the successful creation of an Entity instance.
+   *
+   * @type {Immutable<TModel>}
+   */
+  readonly model: Immutable<TModel>;
+  /**
+   * Keeps track when the Entity's systems have ran last.
+   * Useful to calculate the `DeltaTime` between runs.
+   *
+   * @type {Date | undefined}
+   */
+  readonly lastUpdated?: Date;
+}
+//#endregion
+export { BasicComponentType, ComponentTypeUid, EntityProxy, EntityTypeUid, EntityUid, IComponent, IEntity, IEntityModel, IEntityModelWithFeatures, IEntityModelWithRequiredProxies, IEntityProxy, IEntityProxyRepository, IdentityComponent, RequiredProxies, TypedEntityProxy };
+//# sourceMappingURL=identity-component-CR1ULadR.d.ts.map