@adaas/a-server 0.0.29 → 0.0.31

package/dist/node/lib/A-ServerEntityList/A-EntityList.entity.d.ts

@@ -1,48 +1,72 @@
-import { A_Entity } from '@adaas/a-concept';
+import { A_Entity, A_TYPES__Entity_Constructor, A_Scope } from '@adaas/a-concept';
 import { A_SERVER_TYPES__A_EntityListConstructor, A_SERVER_TYPES__A_EntityListSerialized, A_SERVER_TYPES__A_EntityListPagination } from './A-EntityList.types.js';
+import { A_ServerEntityListPagination } from './A-EntityListPagination.context.js';
 
 /**
  * A-EntityList
  *
- * Entity that represents a list of entities with pagination of particular type
+ * Typed, paginated list of A-Concept entities.
+ *
+ * Construction (user-facing):
+ *   new A_ServerEntityList<User>({ entity: User, pagination: { page: 1, pageSize: 20 } })
+ *
+ * Construction (controller-internal, backward-compat):
+ *   new A_ServerEntityList({ name: 'user', scope: 'my-scope', constructor: User })
  */
-declare class A_ServerEntityList<EntityType extends A_Entity = A_Entity> extends A_Entity<A_SERVER_TYPES__A_EntityListConstructor, A_SERVER_TYPES__A_EntityListSerialized> {
+declare class A_ServerEntityList<EntityType extends A_Entity = A_Entity> extends A_Entity<A_SERVER_TYPES__A_EntityListConstructor<EntityType>, A_SERVER_TYPES__A_EntityListSerialized<EntityType>> {
     static get scope(): string;
-    protected _entityConstructor: new (...args: ConstructorParameters<typeof A_Entity>) => EntityType;
-    protected _items: Array<EntityType>;
-    protected _pagination: A_SERVER_TYPES__A_EntityListPagination;
+    protected _entityConstructor: A_TYPES__Entity_Constructor<EntityType>;
     /**
-     * Returns the entity constructor used for the list
+     * Ordered item references for O(1) positional access.
+     * The list's own scope is the authoritative store (enables @A_Inject and
+     * feature chains on items); this array mirrors the same items in order.
      */
-    get entityConstructor(): new (...args: ConstructorParameters<typeof A_Entity>) => EntityType;
+    protected _items: Array<EntityType>;
+    /** Lazily allocated private scope — pagination and cache state live here. */
+    private _ownScope?;
     /**
-     * Returns the list of items contained in the entity list
+     * The list's own scope, created on first access and bound to this entity
+     * via A_Context.allocate.  Items, pagination and cache state are registered
+     * here so they participate in feature chains and @A_Inject resolution.
      */
+    get ownScope(): A_Scope;
+    get entityConstructor(): A_TYPES__Entity_Constructor<EntityType>;
     get items(): Array<EntityType>;
+    /** Pagination state — lives as a Fragment in the list's own scope. */
+    get pagination(): A_ServerEntityListPagination;
+    private get cacheState();
+    /** Total number of items currently held in memory. */
+    get length(): number;
+    fromNew(newEntity: A_SERVER_TYPES__A_EntityListConstructor<EntityType>): void;
     /**
-     * Returns pagination information about the entity list
-     */
-    get pagination(): A_SERVER_TYPES__A_EntityListPagination;
-    /**
-     * Creates a new instance of A_EntityList
-     *
-     * @param newEntity
-     */
-    fromNew(newEntity: A_SERVER_TYPES__A_EntityListConstructor): void;
-    /**
-     * Allows to convert Repository Response data to EntityList instance
-     *
-     * [!] This method does not load the data from the repository, it only converts the data to the EntityList instance
-     *
-     * @param items
-     * @param pagination
+     * Populate the list from raw repository data.
+     * Items are registered in the list's own scope so they participate in
+     * feature chains and @A_Inject resolution.
      */
     fromList(items: Array<EntityType> | Array<ReturnType<EntityType['toJSON']>>, pagination?: A_SERVER_TYPES__A_EntityListPagination): void;
+    /** Return the item at `index`, or `undefined` if out of range. */
+    at(index: number): EntityType | undefined;
+    /** Replace the item at `index` in place. Accepts a live entity or a plain serialised object. */
+    replace(index: number, item: EntityType | ReturnType<EntityType['toJSON']>): this;
+    /** Append an item to the end of the list. */
+    push(item: EntityType | ReturnType<EntityType['toJSON']>): this;
+    /** Prepend an item to the beginning of the list. */
+    unshift(item: EntityType | ReturnType<EntityType['toJSON']>): this;
+    /** Remove the item at `index` from the list. */
+    remove(index: number): this;
+    /** Return the first item that satisfies `predicate`, or `undefined`. */
+    find(predicate: (item: EntityType, index: number) => boolean): EntityType | undefined;
+    /** Return all items that satisfy `predicate` without mutating the list. */
+    filter(predicate: (item: EntityType, index: number) => boolean): EntityType[];
     /**
-     * Serializes the EntityList to a JSON object
-     *
-     * @returns
+     * Mark this list as cached for `ttlMs` milliseconds from now.
+     * Callers can check `isCached()` to decide whether to skip `load()`.
      */
+    setCache(ttlMs: number): this;
+    /** Returns `true` if the cache is still valid. */
+    isCached(): boolean;
+    /** Invalidate the cache so the next `load()` call fetches fresh data. */
+    invalidateCache(): this;
     toJSON(): A_SERVER_TYPES__A_EntityListSerialized<EntityType>;
 }
 

package/dist/node/lib/A-ServerEntityList/A-EntityList.entity.js

@@ -1,87 +1,160 @@
 'use strict';
 
 var aConcept = require('@adaas/a-concept');
+var AEntityListPagination_context = require('./A-EntityListPagination.context');
+var AEntityListCacheState_context = require('./A-EntityListCacheState.context');
 
 class A_ServerEntityList extends aConcept.A_Entity {
   constructor() {
     super(...arguments);
+    /**
+     * Ordered item references for O(1) positional access.
+     * The list's own scope is the authoritative store (enables @A_Inject and
+     * feature chains on items); this array mirrors the same items in order.
+     */
     this._items = [];
-    this._pagination = {
-      total: 0,
-      page: 1,
-      pageSize: 10
-    };
   }
   static get scope() {
     return "a-server";
   }
+  // ── Getters ──────────────────────────────────────────────────────────────
   /**
-   * Returns the entity constructor used for the list
+   * The list's own scope, created on first access and bound to this entity
+   * via A_Context.allocate.  Items, pagination and cache state are registered
+   * here so they participate in feature chains and @A_Inject resolution.
    */
+  get ownScope() {
+    if (!this._ownScope) {
+      this._ownScope = aConcept.A_Context.allocate(
+        this,
+        new aConcept.A_Scope({ name: `${this.aseid.id}-scope` })
+      );
+    }
+    return this._ownScope;
+  }
   get entityConstructor() {
     return this._entityConstructor;
   }
-  /**
-   * Returns the list of items contained in the entity list
-   */
   get items() {
     return this._items;
   }
-  /**
-   * Returns pagination information about the entity list
-   */
+  /** Pagination state — lives as a Fragment in the list's own scope. */
   get pagination() {
-    return this._pagination;
+    return this.ownScope.resolveFlatOnce(AEntityListPagination_context.A_ServerEntityListPagination);
   }
-  /**
-   * Creates a new instance of A_EntityList
-   * 
-   * @param newEntity 
-   */
+  get cacheState() {
+    return this.ownScope.resolveFlatOnce(AEntityListCacheState_context.A_ServerEntityListCacheState);
+  }
+  /** Total number of items currently held in memory. */
+  get length() {
+    return this._items.length;
+  }
+  // ── Initialisation ───────────────────────────────────────────────────────
   fromNew(newEntity) {
-    this.aseid = new aConcept.ASEID({
+    this.aseid = this.generateASEID({
       concept: aConcept.A_Context.root.name,
-      scope: "default",
-      entity: "a-list" + (newEntity.name ? `.${newEntity.name}` : ""),
-      id: (/* @__PURE__ */ new Date()).getTime().toString()
+      entity: "a-list." + newEntity.entity.name
     });
-    this._entityConstructor = newEntity.constructor;
+    this._entityConstructor = newEntity.entity;
+    this.ownScope.register(new AEntityListPagination_context.A_ServerEntityListPagination(newEntity.pagination));
+    this.ownScope.register(new AEntityListCacheState_context.A_ServerEntityListCacheState());
   }
   /**
-   * Allows to convert Repository Response data to EntityList instance
-   * 
-   * [!] This method does not load the data from the repository, it only converts the data to the EntityList instance
-   * 
-   * @param items 
-   * @param pagination 
+   * Populate the list from raw repository data.
+   * Items are registered in the list's own scope so they participate in
+   * feature chains and @A_Inject resolution.
    */
   fromList(items, pagination) {
-    this._items = items.map((item) => {
-      if (item instanceof aConcept.A_Entity) {
-        return item;
-      } else {
-        const entity = new this._entityConstructor(item);
-        return entity;
+    this._items.forEach((item) => {
+      try {
+        this.ownScope.deregister(item);
+      } catch {
       }
     });
+    this._items = items.map((item) => {
+      const entity = item instanceof aConcept.A_Entity ? item : new this._entityConstructor(item);
+      this.ownScope.register(entity);
+      return entity;
+    });
     if (pagination) {
-      this._pagination = {
-        total: pagination.total,
-        page: pagination.page,
-        pageSize: pagination.pageSize
-      };
+      this.pagination.update(pagination);
     }
   }
+  // ── Collection access ────────────────────────────────────────────────────
+  /** Return the item at `index`, or `undefined` if out of range. */
+  at(index) {
+    return this._items[index];
+  }
+  /** Replace the item at `index` in place. Accepts a live entity or a plain serialised object. */
+  replace(index, item) {
+    const next = item instanceof aConcept.A_Entity ? item : new this._entityConstructor(item);
+    try {
+      this.ownScope.deregister(this._items[index]);
+    } catch {
+    }
+    this.ownScope.register(next);
+    this._items[index] = next;
+    return this;
+  }
+  /** Append an item to the end of the list. */
+  push(item) {
+    const next = item instanceof aConcept.A_Entity ? item : new this._entityConstructor(item);
+    this.ownScope.register(next);
+    this._items.push(next);
+    return this;
+  }
+  /** Prepend an item to the beginning of the list. */
+  unshift(item) {
+    const next = item instanceof aConcept.A_Entity ? item : new this._entityConstructor(item);
+    this.ownScope.register(next);
+    this._items.unshift(next);
+    return this;
+  }
+  /** Remove the item at `index` from the list. */
+  remove(index) {
+    const [removed] = this._items.splice(index, 1);
+    if (removed) {
+      try {
+        this.ownScope.deregister(removed);
+      } catch {
+      }
+    }
+    return this;
+  }
+  /** Return the first item that satisfies `predicate`, or `undefined`. */
+  find(predicate) {
+    return this._items.find(predicate);
+  }
+  /** Return all items that satisfy `predicate` without mutating the list. */
+  filter(predicate) {
+    return this._items.filter(predicate);
+  }
+  // ── Caching ──────────────────────────────────────────────────────────────
   /**
-   * Serializes the EntityList to a JSON object
-   * 
-   * @returns 
+   * Mark this list as cached for `ttlMs` milliseconds from now.
+   * Callers can check `isCached()` to decide whether to skip `load()`.
    */
+  setCache(ttlMs) {
+    this.cacheState.set(ttlMs);
+    return this;
+  }
+  /** Returns `true` if the cache is still valid. */
+  isCached() {
+    return this.cacheState.isValid();
+  }
+  /** Invalidate the cache so the next `load()` call fetches fresh data. */
+  invalidateCache() {
+    this.cacheState.invalidate();
+    return this;
+  }
+  // ── Serialisation ────────────────────────────────────────────────────────
   toJSON() {
+    const { total, page, pageSize } = this.pagination;
     return {
       ...super.toJSON(),
       items: this._items.map((i) => i.toJSON()),
-      pagination: this._pagination
+      type: this._entityConstructor.entity ?? "unknown",
+      pagination: { total, page, pageSize }
     };
   }
 }

package/dist/node/lib/A-ServerEntityList/A-EntityList.entity.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../src/lib/A-ServerEntityList/A-EntityList.entity.ts"],"names":["A_Entity","ASEID","A_Context"],"mappings":";;;;AAiBO,MAAM,2BAEHA,iBAAA,CAGR;AAAA,EALK,WAAA,GAAA;AAAA,IAAA,KAAA,CAAA,GAAA,SAAA,CAAA;AAYH,IAAA,IAAA,CAAU,SAA4B,EAAC;AACvC,IAAA,IAAA,CAAU,WAAA,GAAsD;AAAA,MAC5D,KAAA,EAAO,CAAA;AAAA,MACP,IAAA,EAAM,CAAA;AAAA,MACN,QAAA,EAAU;AAAA,KACd;AAAA,EAAA;AAAA,EAVA,WAAW,KAAA,GAAgB;AACvB,IAAA,OAAO,UAAA;AAAA,EACX;AAAA;AAAA;AAAA;AAAA,EAcA,IAAI,iBAAA,GAAyF;AACzF,IAAA,OAAO,IAAA,CAAK,kBAAA;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,KAAA,GAA2B;AAC3B,IAAA,OAAO,IAAA,CAAK,MAAA;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,UAAA,GAAqD;AACrD,IAAA,OAAO,IAAA,CAAK,WAAA;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,QAAQ,SAAA,EAA0D;AAC9D,IAAA,IAAA,CAAK,KAAA,GAAQ,IAAIC,cAAA,CAAM;AAAA,MACnB,OAAA,EAASC,mBAAU,IAAA,CAAK,IAAA;AAAA,MACxB,KAAA,EAAO,SAAA;AAAA,MACP,QAAQ,QAAA,IAAY,SAAA,CAAU,OAAO,CAAA,CAAA,EAAI,SAAA,CAAU,IAAI,CAAA,CAAA,GAAK,EAAA,CAAA;AAAA,MAC5D,qBAAK,IAAI,IAAA,EAAK,EAAG,OAAA,GAAU,QAAA;AAAS,KACvC,CAAA;AAED,IAAA,IAAA,CAAK,qBAAqB,SAAA,CAAU,WAAA;AAAA,EACxC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,QAAA,CACI,OACA,UAAA,EACF;AACE,IAAA,IAAA,CAAK,MAAA,GAAS,KAAA,CAAM,GAAA,CAAI,CAAA,IAAA,KAAQ;AAC5B,MAAA,IAAI,gBAAgBF,iBAAA,EAAU;AAC1B,QAAA,OAAO,IAAA;AAAA,MACX,CAAA,MAAO;AACH,QAAA,MAAM,MAAA,GAAS,IAAI,IAAA,CAAK,kBAAA,CAAmB,IAAI,CAAA;AAC/C,QAAA,OAAO,MAAA;AAAA,MACX;AAAA,IACJ,CAAC,CAAA;AAED,IAAA,IAAI,UAAA,EAAY;AACZ,MAAA,IAAA,CAAK,WAAA,GAAc;AAAA,QACf,OAAO,UAAA,CAAW,KAAA;AAAA,QAClB,MAAM,UAAA,CAAW,IAAA;AAAA,QACjB,UAAU,UAAA,CAAW;AAAA,OACzB;AAAA,IACJ;AAAA,EACJ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAA,GAA6D;AACzD,IAAA,OAAO;AAAA,MACH,GAAG,MAAM,MAAA,EAAO;AAAA,MAChB,OAAO,IAAA,CAAK,MAAA,CAAO,IAAI,CAAA,CAAA,KAAK,CAAA,CAAE,QAAQ,CAAA;AAAA,MACtC,YAAY,IAAA,CAAK;AAAA,KACrB;AAAA,EACJ;AACJ","file":"A-EntityList.entity.js","sourcesContent":["import {\n    A_Context, A_Entity,\n    ASEID,\n} from \"@adaas/a-concept\";\nimport {\n    A_SERVER_TYPES__A_EntityListConstructor,\n    A_SERVER_TYPES__A_EntityListPagination,\n    A_SERVER_TYPES__A_EntityListSerialized\n} from \"./A-EntityList.types\";\n\n\n\n/**\n * A-EntityList\n * \n * Entity that represents a list of entities with pagination of particular type\n */\nexport class A_ServerEntityList<\n    EntityType extends A_Entity = A_Entity,\n> extends A_Entity<\n    A_SERVER_TYPES__A_EntityListConstructor,\n    A_SERVER_TYPES__A_EntityListSerialized\n> {\n\n    static get scope(): string {\n        return 'a-server';\n    }\n\n    protected _entityConstructor!: new (...args: ConstructorParameters<typeof A_Entity>) => EntityType;\n    protected _items: Array<EntityType> = [];\n    protected _pagination: A_SERVER_TYPES__A_EntityListPagination = {\n        total: 0,\n        page: 1,\n        pageSize: 10\n    };\n\n\n    /**\n     * Returns the entity constructor used for the list\n     */\n    get entityConstructor(): new (...args: ConstructorParameters<typeof A_Entity>) => EntityType {\n        return this._entityConstructor;\n    }\n\n    /**\n     * Returns the list of items contained in the entity list\n     */\n    get items(): Array<EntityType> {\n        return this._items;\n    }\n\n    /**\n     * Returns pagination information about the entity list\n     */\n    get pagination(): A_SERVER_TYPES__A_EntityListPagination {\n        return this._pagination;\n    }\n\n\n\n\n    /**\n     * Creates a new instance of A_EntityList\n     * \n     * @param newEntity \n     */\n    fromNew(newEntity: A_SERVER_TYPES__A_EntityListConstructor): void {\n        this.aseid = new ASEID({\n            concept: A_Context.root.name,\n            scope: 'default',\n            entity: 'a-list' + (newEntity.name ? `.${newEntity.name}` : ''),\n            id: (new Date()).getTime().toString(),\n        });\n\n        this._entityConstructor = newEntity.constructor as new (...args: any[]) => EntityType;\n    }\n\n\n\n    /**\n     * Allows to convert Repository Response data to EntityList instance\n     * \n     * [!] This method does not load the data from the repository, it only converts the data to the EntityList instance\n     * \n     * @param items \n     * @param pagination \n     */\n    fromList(\n        items: Array<EntityType> | Array<ReturnType<EntityType['toJSON']>>,\n        pagination?: A_SERVER_TYPES__A_EntityListPagination\n    ) {\n        this._items = items.map(item => {\n            if (item instanceof A_Entity) {\n                return item as EntityType;\n            } else {\n                const entity = new this._entityConstructor(item);\n                return entity;\n            }\n        });\n\n        if (pagination) {\n            this._pagination = {\n                total: pagination.total,\n                page: pagination.page,\n                pageSize: pagination.pageSize\n            }\n        }\n    }\n\n\n\n    /**\n     * Serializes the EntityList to a JSON object\n     * \n     * @returns \n     */\n    toJSON(): A_SERVER_TYPES__A_EntityListSerialized<EntityType> {\n        return {\n            ...super.toJSON(),\n            items: this._items.map(i => i.toJSON()) as ReturnType<EntityType['toJSON']>[],\n            pagination: this._pagination\n        }\n    }\n}\n"]}
+{"version":3,"sources":["../../../../src/lib/A-ServerEntityList/A-EntityList.entity.ts"],"names":["A_Entity","A_Context","A_Scope","A_ServerEntityListPagination","A_ServerEntityListCacheState"],"mappings":"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","file":"A-EntityList.entity.js","sourcesContent":["import {\n    A_Context, A_Entity, A_Scope,\n    A_TYPES__Entity_Constructor,\n    ASEID,\n} from \"@adaas/a-concept\";\nimport {\n    A_SERVER_TYPES__A_EntityListConstructor,\n    A_SERVER_TYPES__A_EntityListPagination,\n    A_SERVER_TYPES__A_EntityListSerialized\n} from \"./A-EntityList.types\";\nimport { A_ServerEntityListPagination } from \"./A-EntityListPagination.context\";\nimport { A_ServerEntityListCacheState } from \"./A-EntityListCacheState.context\";\n\n\n\n/**\n * A-EntityList\n *\n * Typed, paginated list of A-Concept entities.\n *\n * Construction (user-facing):\n *   new A_ServerEntityList<User>({ entity: User, pagination: { page: 1, pageSize: 20 } })\n *\n * Construction (controller-internal, backward-compat):\n *   new A_ServerEntityList({ name: 'user', scope: 'my-scope', constructor: User })\n */\nexport class A_ServerEntityList<\n    EntityType extends A_Entity = A_Entity,\n> extends A_Entity<\n    A_SERVER_TYPES__A_EntityListConstructor<EntityType>,\n    A_SERVER_TYPES__A_EntityListSerialized<EntityType>\n> {\n\n    static get scope(): string {\n        return 'a-server';\n    }\n\n    protected _entityConstructor!: A_TYPES__Entity_Constructor<EntityType>;\n\n    /**\n     * Ordered item references for O(1) positional access.\n     * The list's own scope is the authoritative store (enables @A_Inject and\n     * feature chains on items); this array mirrors the same items in order.\n     */\n    protected _items: Array<EntityType> = [];\n\n    /** Lazily allocated private scope — pagination and cache state live here. */\n    private _ownScope?: A_Scope;\n\n\n    // ── Getters ──────────────────────────────────────────────────────────────\n\n    /**\n     * The list's own scope, created on first access and bound to this entity\n     * via A_Context.allocate.  Items, pagination and cache state are registered\n     * here so they participate in feature chains and @A_Inject resolution.\n     */\n    get ownScope(): A_Scope {\n        if (!this._ownScope) {\n            this._ownScope = A_Context.allocate(\n                this,\n                new A_Scope({ name: `${this.aseid.id}-scope` })\n            );\n        }\n        return this._ownScope;\n    }\n\n    get entityConstructor(): A_TYPES__Entity_Constructor<EntityType> {\n        return this._entityConstructor;\n    }\n\n    get items(): Array<EntityType> {\n        return this._items;\n    }\n\n    /** Pagination state — lives as a Fragment in the list's own scope. */\n    get pagination(): A_ServerEntityListPagination {\n        return this.ownScope.resolveFlatOnce(A_ServerEntityListPagination)!;\n    }\n\n    private get cacheState(): A_ServerEntityListCacheState {\n        return this.ownScope.resolveFlatOnce(A_ServerEntityListCacheState)!;\n    }\n\n    /** Total number of items currently held in memory. */\n    get length(): number {\n        return this._items.length;\n    }\n\n\n    // ── Initialisation ───────────────────────────────────────────────────────\n\n    fromNew(newEntity: A_SERVER_TYPES__A_EntityListConstructor<EntityType>): void {\n        this.aseid = this.generateASEID({\n            concept: A_Context.root.name,\n            entity: 'a-list.' + newEntity.entity.name,\n        });\n\n        this._entityConstructor = newEntity.entity;\n\n        // Initialise state Fragments in the list's own scope\n        this.ownScope.register(new A_ServerEntityListPagination(newEntity.pagination));\n        this.ownScope.register(new A_ServerEntityListCacheState());\n    }\n\n\n    /**\n     * Populate the list from raw repository data.\n     * Items are registered in the list's own scope so they participate in\n     * feature chains and @A_Inject resolution.\n     */\n    fromList(\n        items: Array<EntityType> | Array<ReturnType<EntityType['toJSON']>>,\n        pagination?: A_SERVER_TYPES__A_EntityListPagination\n    ) {\n        // Deregister previous items from own scope\n        this._items.forEach(item => {\n            try { this.ownScope.deregister(item); } catch { /* already gone */ }\n        });\n\n        this._items = items.map(item => {\n            const entity = item instanceof A_Entity\n                ? item as EntityType\n                : new this._entityConstructor(item as any);\n            this.ownScope.register(entity);\n            return entity;\n        });\n\n        if (pagination) {\n            this.pagination.update(pagination);\n        }\n    }\n\n\n    // ── Collection access ────────────────────────────────────────────────────\n\n    /** Return the item at `index`, or `undefined` if out of range. */\n    at(index: number): EntityType | undefined {\n        return this._items[index];\n    }\n\n    /** Replace the item at `index` in place. Accepts a live entity or a plain serialised object. */\n    replace(index: number, item: EntityType | ReturnType<EntityType['toJSON']>): this {\n        const next = item instanceof A_Entity\n            ? item as EntityType\n            : new this._entityConstructor(item as any);\n        try { this.ownScope.deregister(this._items[index]); } catch { /* ok */ }\n        this.ownScope.register(next);\n        this._items[index] = next;\n        return this;\n    }\n\n    /** Append an item to the end of the list. */\n    push(item: EntityType | ReturnType<EntityType['toJSON']>): this {\n        const next = item instanceof A_Entity\n            ? item as EntityType\n            : new this._entityConstructor(item as any);\n        this.ownScope.register(next);\n        this._items.push(next);\n        return this;\n    }\n\n    /** Prepend an item to the beginning of the list. */\n    unshift(item: EntityType | ReturnType<EntityType['toJSON']>): this {\n        const next = item instanceof A_Entity\n            ? item as EntityType\n            : new this._entityConstructor(item as any);\n        this.ownScope.register(next);\n        this._items.unshift(next);\n        return this;\n    }\n\n    /** Remove the item at `index` from the list. */\n    remove(index: number): this {\n        const [removed] = this._items.splice(index, 1);\n        if (removed) {\n            try { this.ownScope.deregister(removed); } catch { /* ok */ }\n        }\n        return this;\n    }\n\n    /** Return the first item that satisfies `predicate`, or `undefined`. */\n    find(predicate: (item: EntityType, index: number) => boolean): EntityType | undefined {\n        return this._items.find(predicate);\n    }\n\n    /** Return all items that satisfy `predicate` without mutating the list. */\n    filter(predicate: (item: EntityType, index: number) => boolean): EntityType[] {\n        return this._items.filter(predicate);\n    }\n\n\n    // ── Caching ──────────────────────────────────────────────────────────────\n\n    /**\n     * Mark this list as cached for `ttlMs` milliseconds from now.\n     * Callers can check `isCached()` to decide whether to skip `load()`.\n     */\n    setCache(ttlMs: number): this {\n        this.cacheState.set(ttlMs);\n        return this;\n    }\n\n    /** Returns `true` if the cache is still valid. */\n    isCached(): boolean {\n        return this.cacheState.isValid();\n    }\n\n    /** Invalidate the cache so the next `load()` call fetches fresh data. */\n    invalidateCache(): this {\n        this.cacheState.invalidate();\n        return this;\n    }\n\n\n    // ── Serialisation ────────────────────────────────────────────────────────\n\n    toJSON(): A_SERVER_TYPES__A_EntityListSerialized<EntityType> {\n        const { total, page, pageSize } = this.pagination;\n        return {\n            ...super.toJSON(),\n            items: this._items.map(i => i.toJSON()) as ReturnType<EntityType['toJSON']>[],\n            type: (this._entityConstructor as any).entity ?? 'unknown',\n            pagination: { total, page, pageSize },\n        };\n    }\n}\n\n"]}

package/dist/node/lib/A-ServerEntityList/A-EntityList.entity.mjs

@@ -1,86 +1,159 @@
 import '../../chunk-EQQGB2QZ.mjs';
-import { A_Entity, ASEID, A_Context } from '@adaas/a-concept';
+import { A_Entity, A_Context, A_Scope } from '@adaas/a-concept';
+import { A_ServerEntityListPagination } from './A-EntityListPagination.context';
+import { A_ServerEntityListCacheState } from './A-EntityListCacheState.context';
 
 class A_ServerEntityList extends A_Entity {
   constructor() {
     super(...arguments);
+    /**
+     * Ordered item references for O(1) positional access.
+     * The list's own scope is the authoritative store (enables @A_Inject and
+     * feature chains on items); this array mirrors the same items in order.
+     */
     this._items = [];
-    this._pagination = {
-      total: 0,
-      page: 1,
-      pageSize: 10
-    };
   }
   static get scope() {
     return "a-server";
   }
+  // ── Getters ──────────────────────────────────────────────────────────────
   /**
-   * Returns the entity constructor used for the list
+   * The list's own scope, created on first access and bound to this entity
+   * via A_Context.allocate.  Items, pagination and cache state are registered
+   * here so they participate in feature chains and @A_Inject resolution.
    */
+  get ownScope() {
+    if (!this._ownScope) {
+      this._ownScope = A_Context.allocate(
+        this,
+        new A_Scope({ name: `${this.aseid.id}-scope` })
+      );
+    }
+    return this._ownScope;
+  }
   get entityConstructor() {
     return this._entityConstructor;
   }
-  /**
-   * Returns the list of items contained in the entity list
-   */
   get items() {
     return this._items;
   }
-  /**
-   * Returns pagination information about the entity list
-   */
+  /** Pagination state — lives as a Fragment in the list's own scope. */
   get pagination() {
-    return this._pagination;
+    return this.ownScope.resolveFlatOnce(A_ServerEntityListPagination);
   }
-  /**
-   * Creates a new instance of A_EntityList
-   * 
-   * @param newEntity 
-   */
+  get cacheState() {
+    return this.ownScope.resolveFlatOnce(A_ServerEntityListCacheState);
+  }
+  /** Total number of items currently held in memory. */
+  get length() {
+    return this._items.length;
+  }
+  // ── Initialisation ───────────────────────────────────────────────────────
   fromNew(newEntity) {
-    this.aseid = new ASEID({
+    this.aseid = this.generateASEID({
       concept: A_Context.root.name,
-      scope: "default",
-      entity: "a-list" + (newEntity.name ? `.${newEntity.name}` : ""),
-      id: (/* @__PURE__ */ new Date()).getTime().toString()
+      entity: "a-list." + newEntity.entity.name
     });
-    this._entityConstructor = newEntity.constructor;
+    this._entityConstructor = newEntity.entity;
+    this.ownScope.register(new A_ServerEntityListPagination(newEntity.pagination));
+    this.ownScope.register(new A_ServerEntityListCacheState());
   }
   /**
-   * Allows to convert Repository Response data to EntityList instance
-   * 
-   * [!] This method does not load the data from the repository, it only converts the data to the EntityList instance
-   * 
-   * @param items 
-   * @param pagination 
+   * Populate the list from raw repository data.
+   * Items are registered in the list's own scope so they participate in
+   * feature chains and @A_Inject resolution.
    */
   fromList(items, pagination) {
-    this._items = items.map((item) => {
-      if (item instanceof A_Entity) {
-        return item;
-      } else {
-        const entity = new this._entityConstructor(item);
-        return entity;
+    this._items.forEach((item) => {
+      try {
+        this.ownScope.deregister(item);
+      } catch {
       }
     });
+    this._items = items.map((item) => {
+      const entity = item instanceof A_Entity ? item : new this._entityConstructor(item);
+      this.ownScope.register(entity);
+      return entity;
+    });
     if (pagination) {
-      this._pagination = {
-        total: pagination.total,
-        page: pagination.page,
-        pageSize: pagination.pageSize
-      };
+      this.pagination.update(pagination);
     }
   }
+  // ── Collection access ────────────────────────────────────────────────────
+  /** Return the item at `index`, or `undefined` if out of range. */
+  at(index) {
+    return this._items[index];
+  }
+  /** Replace the item at `index` in place. Accepts a live entity or a plain serialised object. */
+  replace(index, item) {
+    const next = item instanceof A_Entity ? item : new this._entityConstructor(item);
+    try {
+      this.ownScope.deregister(this._items[index]);
+    } catch {
+    }
+    this.ownScope.register(next);
+    this._items[index] = next;
+    return this;
+  }
+  /** Append an item to the end of the list. */
+  push(item) {
+    const next = item instanceof A_Entity ? item : new this._entityConstructor(item);
+    this.ownScope.register(next);
+    this._items.push(next);
+    return this;
+  }
+  /** Prepend an item to the beginning of the list. */
+  unshift(item) {
+    const next = item instanceof A_Entity ? item : new this._entityConstructor(item);
+    this.ownScope.register(next);
+    this._items.unshift(next);
+    return this;
+  }
+  /** Remove the item at `index` from the list. */
+  remove(index) {
+    const [removed] = this._items.splice(index, 1);
+    if (removed) {
+      try {
+        this.ownScope.deregister(removed);
+      } catch {
+      }
+    }
+    return this;
+  }
+  /** Return the first item that satisfies `predicate`, or `undefined`. */
+  find(predicate) {
+    return this._items.find(predicate);
+  }
+  /** Return all items that satisfy `predicate` without mutating the list. */
+  filter(predicate) {
+    return this._items.filter(predicate);
+  }
+  // ── Caching ──────────────────────────────────────────────────────────────
   /**
-   * Serializes the EntityList to a JSON object
-   * 
-   * @returns 
+   * Mark this list as cached for `ttlMs` milliseconds from now.
+   * Callers can check `isCached()` to decide whether to skip `load()`.
    */
+  setCache(ttlMs) {
+    this.cacheState.set(ttlMs);
+    return this;
+  }
+  /** Returns `true` if the cache is still valid. */
+  isCached() {
+    return this.cacheState.isValid();
+  }
+  /** Invalidate the cache so the next `load()` call fetches fresh data. */
+  invalidateCache() {
+    this.cacheState.invalidate();
+    return this;
+  }
+  // ── Serialisation ────────────────────────────────────────────────────────
   toJSON() {
+    const { total, page, pageSize } = this.pagination;
     return {
       ...super.toJSON(),
       items: this._items.map((i) => i.toJSON()),
-      pagination: this._pagination
+      type: this._entityConstructor.entity ?? "unknown",
+      pagination: { total, page, pageSize }
     };
   }
 }

package/dist/node/lib/A-ServerEntityList/A-EntityList.entity.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../src/lib/A-ServerEntityList/A-EntityList.entity.ts"],"names":[],"mappings":";;;AAiBO,MAAM,2BAEH,QAAA,CAGR;AAAA,EALK,WAAA,GAAA;AAAA,IAAA,KAAA,CAAA,GAAA,SAAA,CAAA;AAYH,IAAA,IAAA,CAAU,SAA4B,EAAC;AACvC,IAAA,IAAA,CAAU,WAAA,GAAsD;AAAA,MAC5D,KAAA,EAAO,CAAA;AAAA,MACP,IAAA,EAAM,CAAA;AAAA,MACN,QAAA,EAAU;AAAA,KACd;AAAA,EAAA;AAAA,EAVA,WAAW,KAAA,GAAgB;AACvB,IAAA,OAAO,UAAA;AAAA,EACX;AAAA;AAAA;AAAA;AAAA,EAcA,IAAI,iBAAA,GAAyF;AACzF,IAAA,OAAO,IAAA,CAAK,kBAAA;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,KAAA,GAA2B;AAC3B,IAAA,OAAO,IAAA,CAAK,MAAA;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,UAAA,GAAqD;AACrD,IAAA,OAAO,IAAA,CAAK,WAAA;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,QAAQ,SAAA,EAA0D;AAC9D,IAAA,IAAA,CAAK,KAAA,GAAQ,IAAI,KAAA,CAAM;AAAA,MACnB,OAAA,EAAS,UAAU,IAAA,CAAK,IAAA;AAAA,MACxB,KAAA,EAAO,SAAA;AAAA,MACP,QAAQ,QAAA,IAAY,SAAA,CAAU,OAAO,CAAA,CAAA,EAAI,SAAA,CAAU,IAAI,CAAA,CAAA,GAAK,EAAA,CAAA;AAAA,MAC5D,qBAAK,IAAI,IAAA,EAAK,EAAG,OAAA,GAAU,QAAA;AAAS,KACvC,CAAA;AAED,IAAA,IAAA,CAAK,qBAAqB,SAAA,CAAU,WAAA;AAAA,EACxC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,QAAA,CACI,OACA,UAAA,EACF;AACE,IAAA,IAAA,CAAK,MAAA,GAAS,KAAA,CAAM,GAAA,CAAI,CAAA,IAAA,KAAQ;AAC5B,MAAA,IAAI,gBAAgB,QAAA,EAAU;AAC1B,QAAA,OAAO,IAAA;AAAA,MACX,CAAA,MAAO;AACH,QAAA,MAAM,MAAA,GAAS,IAAI,IAAA,CAAK,kBAAA,CAAmB,IAAI,CAAA;AAC/C,QAAA,OAAO,MAAA;AAAA,MACX;AAAA,IACJ,CAAC,CAAA;AAED,IAAA,IAAI,UAAA,EAAY;AACZ,MAAA,IAAA,CAAK,WAAA,GAAc;AAAA,QACf,OAAO,UAAA,CAAW,KAAA;AAAA,QAClB,MAAM,UAAA,CAAW,IAAA;AAAA,QACjB,UAAU,UAAA,CAAW;AAAA,OACzB;AAAA,IACJ;AAAA,EACJ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAA,GAA6D;AACzD,IAAA,OAAO;AAAA,MACH,GAAG,MAAM,MAAA,EAAO;AAAA,MAChB,OAAO,IAAA,CAAK,MAAA,CAAO,IAAI,CAAA,CAAA,KAAK,CAAA,CAAE,QAAQ,CAAA;AAAA,MACtC,YAAY,IAAA,CAAK;AAAA,KACrB;AAAA,EACJ;AACJ","file":"A-EntityList.entity.mjs","sourcesContent":["import {\n    A_Context, A_Entity,\n    ASEID,\n} from \"@adaas/a-concept\";\nimport {\n    A_SERVER_TYPES__A_EntityListConstructor,\n    A_SERVER_TYPES__A_EntityListPagination,\n    A_SERVER_TYPES__A_EntityListSerialized\n} from \"./A-EntityList.types\";\n\n\n\n/**\n * A-EntityList\n * \n * Entity that represents a list of entities with pagination of particular type\n */\nexport class A_ServerEntityList<\n    EntityType extends A_Entity = A_Entity,\n> extends A_Entity<\n    A_SERVER_TYPES__A_EntityListConstructor,\n    A_SERVER_TYPES__A_EntityListSerialized\n> {\n\n    static get scope(): string {\n        return 'a-server';\n    }\n\n    protected _entityConstructor!: new (...args: ConstructorParameters<typeof A_Entity>) => EntityType;\n    protected _items: Array<EntityType> = [];\n    protected _pagination: A_SERVER_TYPES__A_EntityListPagination = {\n        total: 0,\n        page: 1,\n        pageSize: 10\n    };\n\n\n    /**\n     * Returns the entity constructor used for the list\n     */\n    get entityConstructor(): new (...args: ConstructorParameters<typeof A_Entity>) => EntityType {\n        return this._entityConstructor;\n    }\n\n    /**\n     * Returns the list of items contained in the entity list\n     */\n    get items(): Array<EntityType> {\n        return this._items;\n    }\n\n    /**\n     * Returns pagination information about the entity list\n     */\n    get pagination(): A_SERVER_TYPES__A_EntityListPagination {\n        return this._pagination;\n    }\n\n\n\n\n    /**\n     * Creates a new instance of A_EntityList\n     * \n     * @param newEntity \n     */\n    fromNew(newEntity: A_SERVER_TYPES__A_EntityListConstructor): void {\n        this.aseid = new ASEID({\n            concept: A_Context.root.name,\n            scope: 'default',\n            entity: 'a-list' + (newEntity.name ? `.${newEntity.name}` : ''),\n            id: (new Date()).getTime().toString(),\n        });\n\n        this._entityConstructor = newEntity.constructor as new (...args: any[]) => EntityType;\n    }\n\n\n\n    /**\n     * Allows to convert Repository Response data to EntityList instance\n     * \n     * [!] This method does not load the data from the repository, it only converts the data to the EntityList instance\n     * \n     * @param items \n     * @param pagination \n     */\n    fromList(\n        items: Array<EntityType> | Array<ReturnType<EntityType['toJSON']>>,\n        pagination?: A_SERVER_TYPES__A_EntityListPagination\n    ) {\n        this._items = items.map(item => {\n            if (item instanceof A_Entity) {\n                return item as EntityType;\n            } else {\n                const entity = new this._entityConstructor(item);\n                return entity;\n            }\n        });\n\n        if (pagination) {\n            this._pagination = {\n                total: pagination.total,\n                page: pagination.page,\n                pageSize: pagination.pageSize\n            }\n        }\n    }\n\n\n\n    /**\n     * Serializes the EntityList to a JSON object\n     * \n     * @returns \n     */\n    toJSON(): A_SERVER_TYPES__A_EntityListSerialized<EntityType> {\n        return {\n            ...super.toJSON(),\n            items: this._items.map(i => i.toJSON()) as ReturnType<EntityType['toJSON']>[],\n            pagination: this._pagination\n        }\n    }\n}\n"]}
+{"version":3,"sources":["../../../../src/lib/A-ServerEntityList/A-EntityList.entity.ts"],"names":[],"mappings":"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","file":"A-EntityList.entity.mjs","sourcesContent":["import {\n    A_Context, A_Entity, A_Scope,\n    A_TYPES__Entity_Constructor,\n    ASEID,\n} from \"@adaas/a-concept\";\nimport {\n    A_SERVER_TYPES__A_EntityListConstructor,\n    A_SERVER_TYPES__A_EntityListPagination,\n    A_SERVER_TYPES__A_EntityListSerialized\n} from \"./A-EntityList.types\";\nimport { A_ServerEntityListPagination } from \"./A-EntityListPagination.context\";\nimport { A_ServerEntityListCacheState } from \"./A-EntityListCacheState.context\";\n\n\n\n/**\n * A-EntityList\n *\n * Typed, paginated list of A-Concept entities.\n *\n * Construction (user-facing):\n *   new A_ServerEntityList<User>({ entity: User, pagination: { page: 1, pageSize: 20 } })\n *\n * Construction (controller-internal, backward-compat):\n *   new A_ServerEntityList({ name: 'user', scope: 'my-scope', constructor: User })\n */\nexport class A_ServerEntityList<\n    EntityType extends A_Entity = A_Entity,\n> extends A_Entity<\n    A_SERVER_TYPES__A_EntityListConstructor<EntityType>,\n    A_SERVER_TYPES__A_EntityListSerialized<EntityType>\n> {\n\n    static get scope(): string {\n        return 'a-server';\n    }\n\n    protected _entityConstructor!: A_TYPES__Entity_Constructor<EntityType>;\n\n    /**\n     * Ordered item references for O(1) positional access.\n     * The list's own scope is the authoritative store (enables @A_Inject and\n     * feature chains on items); this array mirrors the same items in order.\n     */\n    protected _items: Array<EntityType> = [];\n\n    /** Lazily allocated private scope — pagination and cache state live here. */\n    private _ownScope?: A_Scope;\n\n\n    // ── Getters ──────────────────────────────────────────────────────────────\n\n    /**\n     * The list's own scope, created on first access and bound to this entity\n     * via A_Context.allocate.  Items, pagination and cache state are registered\n     * here so they participate in feature chains and @A_Inject resolution.\n     */\n    get ownScope(): A_Scope {\n        if (!this._ownScope) {\n            this._ownScope = A_Context.allocate(\n                this,\n                new A_Scope({ name: `${this.aseid.id}-scope` })\n            );\n        }\n        return this._ownScope;\n    }\n\n    get entityConstructor(): A_TYPES__Entity_Constructor<EntityType> {\n        return this._entityConstructor;\n    }\n\n    get items(): Array<EntityType> {\n        return this._items;\n    }\n\n    /** Pagination state — lives as a Fragment in the list's own scope. */\n    get pagination(): A_ServerEntityListPagination {\n        return this.ownScope.resolveFlatOnce(A_ServerEntityListPagination)!;\n    }\n\n    private get cacheState(): A_ServerEntityListCacheState {\n        return this.ownScope.resolveFlatOnce(A_ServerEntityListCacheState)!;\n    }\n\n    /** Total number of items currently held in memory. */\n    get length(): number {\n        return this._items.length;\n    }\n\n\n    // ── Initialisation ───────────────────────────────────────────────────────\n\n    fromNew(newEntity: A_SERVER_TYPES__A_EntityListConstructor<EntityType>): void {\n        this.aseid = this.generateASEID({\n            concept: A_Context.root.name,\n            entity: 'a-list.' + newEntity.entity.name,\n        });\n\n        this._entityConstructor = newEntity.entity;\n\n        // Initialise state Fragments in the list's own scope\n        this.ownScope.register(new A_ServerEntityListPagination(newEntity.pagination));\n        this.ownScope.register(new A_ServerEntityListCacheState());\n    }\n\n\n    /**\n     * Populate the list from raw repository data.\n     * Items are registered in the list's own scope so they participate in\n     * feature chains and @A_Inject resolution.\n     */\n    fromList(\n        items: Array<EntityType> | Array<ReturnType<EntityType['toJSON']>>,\n        pagination?: A_SERVER_TYPES__A_EntityListPagination\n    ) {\n        // Deregister previous items from own scope\n        this._items.forEach(item => {\n            try { this.ownScope.deregister(item); } catch { /* already gone */ }\n        });\n\n        this._items = items.map(item => {\n            const entity = item instanceof A_Entity\n                ? item as EntityType\n                : new this._entityConstructor(item as any);\n            this.ownScope.register(entity);\n            return entity;\n        });\n\n        if (pagination) {\n            this.pagination.update(pagination);\n        }\n    }\n\n\n    // ── Collection access ────────────────────────────────────────────────────\n\n    /** Return the item at `index`, or `undefined` if out of range. */\n    at(index: number): EntityType | undefined {\n        return this._items[index];\n    }\n\n    /** Replace the item at `index` in place. Accepts a live entity or a plain serialised object. */\n    replace(index: number, item: EntityType | ReturnType<EntityType['toJSON']>): this {\n        const next = item instanceof A_Entity\n            ? item as EntityType\n            : new this._entityConstructor(item as any);\n        try { this.ownScope.deregister(this._items[index]); } catch { /* ok */ }\n        this.ownScope.register(next);\n        this._items[index] = next;\n        return this;\n    }\n\n    /** Append an item to the end of the list. */\n    push(item: EntityType | ReturnType<EntityType['toJSON']>): this {\n        const next = item instanceof A_Entity\n            ? item as EntityType\n            : new this._entityConstructor(item as any);\n        this.ownScope.register(next);\n        this._items.push(next);\n        return this;\n    }\n\n    /** Prepend an item to the beginning of the list. */\n    unshift(item: EntityType | ReturnType<EntityType['toJSON']>): this {\n        const next = item instanceof A_Entity\n            ? item as EntityType\n            : new this._entityConstructor(item as any);\n        this.ownScope.register(next);\n        this._items.unshift(next);\n        return this;\n    }\n\n    /** Remove the item at `index` from the list. */\n    remove(index: number): this {\n        const [removed] = this._items.splice(index, 1);\n        if (removed) {\n            try { this.ownScope.deregister(removed); } catch { /* ok */ }\n        }\n        return this;\n    }\n\n    /** Return the first item that satisfies `predicate`, or `undefined`. */\n    find(predicate: (item: EntityType, index: number) => boolean): EntityType | undefined {\n        return this._items.find(predicate);\n    }\n\n    /** Return all items that satisfy `predicate` without mutating the list. */\n    filter(predicate: (item: EntityType, index: number) => boolean): EntityType[] {\n        return this._items.filter(predicate);\n    }\n\n\n    // ── Caching ──────────────────────────────────────────────────────────────\n\n    /**\n     * Mark this list as cached for `ttlMs` milliseconds from now.\n     * Callers can check `isCached()` to decide whether to skip `load()`.\n     */\n    setCache(ttlMs: number): this {\n        this.cacheState.set(ttlMs);\n        return this;\n    }\n\n    /** Returns `true` if the cache is still valid. */\n    isCached(): boolean {\n        return this.cacheState.isValid();\n    }\n\n    /** Invalidate the cache so the next `load()` call fetches fresh data. */\n    invalidateCache(): this {\n        this.cacheState.invalidate();\n        return this;\n    }\n\n\n    // ── Serialisation ────────────────────────────────────────────────────────\n\n    toJSON(): A_SERVER_TYPES__A_EntityListSerialized<EntityType> {\n        const { total, page, pageSize } = this.pagination;\n        return {\n            ...super.toJSON(),\n            items: this._items.map(i => i.toJSON()) as ReturnType<EntityType['toJSON']>[],\n            type: (this._entityConstructor as any).entity ?? 'unknown',\n            pagination: { total, page, pageSize },\n        };\n    }\n}\n\n"]}

package/dist/node/lib/A-ServerEntityList/A-EntityList.types.d.mts

@@ -1,9 +1,13 @@
-import { A_TYPES__Entity_Constructor, A_Entity, A_TYPES__Entity_Serialized } from '@adaas/a-concept';
+import { A_Entity, A_TYPES__Entity_Constructor, A_TYPES__Entity_Serialized } from '@adaas/a-concept';
 
-type A_SERVER_TYPES__A_EntityListConstructor = {
-    name: string;
-    scope: string;
-    constructor: A_TYPES__Entity_Constructor;
+type A_SERVER_TYPES__A_EntityListConstructor<T extends A_Entity = A_Entity> = {
+    /** User-facing: the entity class (e.g. `User`). Name and scope are derived from its statics. */
+    entity: A_TYPES__Entity_Constructor<T>;
+    /** Initial pagination request parameters. Defaults to page 1, pageSize 10. */
+    pagination?: {
+        page?: number;
+        pageSize?: number;
+    };
 };
 declare enum A_SERVER_TYPES__A_EntityListEvent {
     Load = "load"
@@ -18,5 +22,9 @@ type A_SERVER_TYPES__A_EntityListPagination = {
     page: number;
     pageSize: number;
 };
+type A_SERVER_TYPES__A_EntityListCacheEntry = {
+    timestamp: number;
+    ttl: number;
+};
 
-export { type A_SERVER_TYPES__A_EntityListConstructor, A_SERVER_TYPES__A_EntityListEvent, type A_SERVER_TYPES__A_EntityListPagination, type A_SERVER_TYPES__A_EntityListSerialized };
+export { type A_SERVER_TYPES__A_EntityListCacheEntry, type A_SERVER_TYPES__A_EntityListConstructor, A_SERVER_TYPES__A_EntityListEvent, type A_SERVER_TYPES__A_EntityListPagination, type A_SERVER_TYPES__A_EntityListSerialized };