@adaas/a-server 0.0.29 → 0.0.31

package/src/lib/A-ServerEntityList/A-EntityList.entity.ts

@@ -1,5 +1,6 @@
 import {
-    A_Context, A_Entity,
+    A_Context, A_Entity, A_Scope,
+    A_TYPES__Entity_Constructor,
     ASEID,
 } from "@adaas/a-concept";
 import {
@@ -7,118 +8,221 @@ import {
     A_SERVER_TYPES__A_EntityListPagination,
     A_SERVER_TYPES__A_EntityListSerialized
 } from "./A-EntityList.types";
+import { A_ServerEntityListPagination } from "./A-EntityListPagination.context";
+import { A_ServerEntityListCacheState } from "./A-EntityListCacheState.context";
 
 
 
 /**
  * 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 })
  */
 export class A_ServerEntityList<
     EntityType extends A_Entity = A_Entity,
 > extends A_Entity<
-    A_SERVER_TYPES__A_EntityListConstructor,
-    A_SERVER_TYPES__A_EntityListSerialized
+    A_SERVER_TYPES__A_EntityListConstructor<EntityType>,
+    A_SERVER_TYPES__A_EntityListSerialized<EntityType>
 > {
 
     static get scope(): string {
         return 'a-server';
     }
 
-    protected _entityConstructor!: new (...args: ConstructorParameters<typeof A_Entity>) => EntityType;
+    protected _entityConstructor!: A_TYPES__Entity_Constructor<EntityType>;
+
+    /**
+     * 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.
+     */
     protected _items: Array<EntityType> = [];
-    protected _pagination: A_SERVER_TYPES__A_EntityListPagination = {
-        total: 0,
-        page: 1,
-        pageSize: 10
-    };
 
+    /** Lazily allocated private scope — pagination and cache state live here. */
+    private _ownScope?: A_Scope;
+
+
+    // ── 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 entityConstructor(): new (...args: ConstructorParameters<typeof A_Entity>) => EntityType {
+    get ownScope(): A_Scope {
+        if (!this._ownScope) {
+            this._ownScope = A_Context.allocate(
+                this,
+                new A_Scope({ name: `${this.aseid.id}-scope` })
+            );
+        }
+        return this._ownScope;
+    }
+
+    get entityConstructor(): A_TYPES__Entity_Constructor<EntityType> {
         return this._entityConstructor;
     }
 
-    /**
-     * Returns the list of items contained in the entity list
-     */
     get items(): Array<EntityType> {
         return this._items;
     }
 
-    /**
-     * Returns pagination information about the entity list
-     */
-    get pagination(): A_SERVER_TYPES__A_EntityListPagination {
-        return this._pagination;
+    /** Pagination state — lives as a Fragment in the list's own scope. */
+    get pagination(): A_ServerEntityListPagination {
+        return this.ownScope.resolveFlatOnce(A_ServerEntityListPagination)!;
+    }
+
+    private get cacheState(): A_ServerEntityListCacheState {
+        return this.ownScope.resolveFlatOnce(A_ServerEntityListCacheState)!;
     }
 
+    /** Total number of items currently held in memory. */
+    get length(): number {
+        return this._items.length;
+    }
 
 
+    // ── Initialisation ───────────────────────────────────────────────────────
 
-    /**
-     * Creates a new instance of A_EntityList
-     * 
-     * @param newEntity 
-     */
-    fromNew(newEntity: A_SERVER_TYPES__A_EntityListConstructor): void {
-        this.aseid = new ASEID({
+    fromNew(newEntity: A_SERVER_TYPES__A_EntityListConstructor<EntityType>): void {
+        this.aseid = this.generateASEID({
             concept: A_Context.root.name,
-            scope: 'default',
-            entity: 'a-list' + (newEntity.name ? `.${newEntity.name}` : ''),
-            id: (new Date()).getTime().toString(),
+            entity: 'a-list.' + newEntity.entity.name,
         });
 
-        this._entityConstructor = newEntity.constructor as new (...args: any[]) => EntityType;
-    }
+        this._entityConstructor = newEntity.entity;
 
+        // Initialise state Fragments in the list's own scope
+        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: Array<EntityType> | Array<ReturnType<EntityType['toJSON']>>,
         pagination?: A_SERVER_TYPES__A_EntityListPagination
     ) {
+        // Deregister previous items from own scope
+        this._items.forEach(item => {
+            try { this.ownScope.deregister(item); } catch { /* already gone */ }
+        });
+
         this._items = items.map(item => {
-            if (item instanceof A_Entity) {
-                return item as EntityType;
-            } else {
-                const entity = new this._entityConstructor(item);
-                return entity;
-            }
+            const entity = item instanceof A_Entity
+                ? item as EntityType
+                : new this._entityConstructor(item as any);
+            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: number): EntityType | undefined {
+        return this._items[index];
+    }
+
+    /** 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 {
+        const next = item instanceof A_Entity
+            ? item as EntityType
+            : new this._entityConstructor(item as any);
+        try { this.ownScope.deregister(this._items[index]); } catch { /* ok */ }
+        this.ownScope.register(next);
+        this._items[index] = next;
+        return this;
+    }
+
+    /** Append an item to the end of the list. */
+    push(item: EntityType | ReturnType<EntityType['toJSON']>): this {
+        const next = item instanceof A_Entity
+            ? item as EntityType
+            : new this._entityConstructor(item as any);
+        this.ownScope.register(next);
+        this._items.push(next);
+        return this;
+    }
+
+    /** Prepend an item to the beginning of the list. */
+    unshift(item: EntityType | ReturnType<EntityType['toJSON']>): this {
+        const next = item instanceof A_Entity
+            ? item as EntityType
+            : new this._entityConstructor(item as any);
+        this.ownScope.register(next);
+        this._items.unshift(next);
+        return this;
+    }
+
+    /** Remove the item at `index` from the list. */
+    remove(index: number): this {
+        const [removed] = this._items.splice(index, 1);
+        if (removed) {
+            try { this.ownScope.deregister(removed); } catch { /* ok */ }
         }
+        return this;
     }
 
+    /** Return the first item that satisfies `predicate`, or `undefined`. */
+    find(predicate: (item: EntityType, index: number) => boolean): EntityType | undefined {
+        return this._items.find(predicate);
+    }
 
+    /** Return all items that satisfy `predicate` without mutating the list. */
+    filter(predicate: (item: EntityType, index: number) => boolean): EntityType[] {
+        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: number): this {
+        this.cacheState.set(ttlMs);
+        return this;
+    }
+
+    /** Returns `true` if the cache is still valid. */
+    isCached(): boolean {
+        return this.cacheState.isValid();
+    }
+
+    /** Invalidate the cache so the next `load()` call fetches fresh data. */
+    invalidateCache(): this {
+        this.cacheState.invalidate();
+        return this;
+    }
+
+
+    // ── Serialisation ────────────────────────────────────────────────────────
+
     toJSON(): A_SERVER_TYPES__A_EntityListSerialized<EntityType> {
+        const { total, page, pageSize } = this.pagination;
         return {
             ...super.toJSON(),
             items: this._items.map(i => i.toJSON()) as ReturnType<EntityType['toJSON']>[],
-            pagination: this._pagination
-        }
+            type: (this._entityConstructor as any).entity ?? 'unknown',
+            pagination: { total, page, pageSize },
+        };
     }
 }
+

package/src/lib/A-ServerEntityList/A-EntityList.types.ts

@@ -1,11 +1,17 @@
 import { A_Entity, A_TYPES__Entity_Constructor, A_TYPES__Entity_Serialized } from "@adaas/a-concept";
 
 
-export type A_SERVER_TYPES__A_EntityListConstructor = {
-    name: string,
-    scope: string,
-    constructor: A_TYPES__Entity_Constructor,
-}
+export 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;
+    };
+};
 
 export enum A_SERVER_TYPES__A_EntityListEvent {
     Load = 'load',
@@ -18,10 +24,14 @@ export type A_SERVER_TYPES__A_EntityListSerialized<EntityTypes extends A_Entity
 } & A_TYPES__Entity_Serialized;
 
 
-
 export type A_SERVER_TYPES__A_EntityListPagination = {
     total: number,
     page: number,
     pageSize: number,
-}
+};
+
+export type A_SERVER_TYPES__A_EntityListCacheEntry = {
+    timestamp: number;
+    ttl: number;
+};
 

package/src/lib/A-ServerEntityList/A-EntityListCacheState.context.ts

@@ -0,0 +1,27 @@
+import { A_Fragment, A_TYPES__Fragment_Serialized } from "@adaas/a-concept";
+
+
+export class A_ServerEntityListCacheState extends A_Fragment<A_TYPES__Fragment_Serialized> {
+
+    protected _timestamp?: number;
+    protected _ttl?: number;
+
+    set(ttlMs: number): void {
+        this._timestamp = Date.now();
+        this._ttl = ttlMs;
+    }
+
+    invalidate(): void {
+        this._timestamp = undefined;
+        this._ttl = undefined;
+    }
+
+    isValid(): boolean {
+        if (this._timestamp === undefined || this._ttl === undefined) return false;
+        return (Date.now() - this._timestamp) < this._ttl;
+    }
+
+    toJSON(): A_TYPES__Fragment_Serialized {
+        return { name: this.name };
+    }
+}

package/src/lib/A-ServerEntityList/A-EntityListPagination.context.ts

@@ -0,0 +1,48 @@
+import { A_Fragment, A_TYPES__Fragment_Serialized } from "@adaas/a-concept";
+import { A_SERVER_TYPES__A_EntityListPagination } from "./A-EntityList.types";
+
+
+export type A_SERVER_TYPES__A_EntityListPaginationSerialized =
+    A_SERVER_TYPES__A_EntityListPagination & A_TYPES__Fragment_Serialized;
+
+
+export class A_ServerEntityListPagination extends A_Fragment<A_SERVER_TYPES__A_EntityListPaginationSerialized> {
+
+    protected _total: number = 0;
+    protected _page: number = 1;
+    protected _pageSize: number = 10;
+
+    constructor(init?: Partial<A_SERVER_TYPES__A_EntityListPagination>) {
+        super();
+        if (init) {
+            if (init.total !== undefined) this._total = init.total;
+            if (init.page !== undefined) this._page = init.page;
+            if (init.pageSize !== undefined) this._pageSize = init.pageSize;
+        }
+    }
+
+    get total(): number { return this._total; }
+    get page(): number { return this._page; }
+    get pageSize(): number { return this._pageSize; }
+
+    update(data: Partial<A_SERVER_TYPES__A_EntityListPagination>): void {
+        if (data.total !== undefined) this._total = data.total;
+        if (data.page !== undefined) this._page = data.page;
+        if (data.pageSize !== undefined) this._pageSize = data.pageSize;
+    }
+
+    fromJSON(serialized: A_SERVER_TYPES__A_EntityListPaginationSerialized): void {
+        this._total = serialized.total;
+        this._page = serialized.page;
+        this._pageSize = serialized.pageSize;
+    }
+
+    toJSON(): A_SERVER_TYPES__A_EntityListPaginationSerialized {
+        return {
+            name: this.name,
+            total: this._total,
+            page: this._page,
+            pageSize: this._pageSize,
+        };
+    }
+}

package/src/lib/A-ServerLogger/A-ServerLogger.component.ts

@@ -1,5 +1,4 @@
-import { A_Error, A_Feature, A_Inject, } from "@adaas/a-concept";
-import { A_Server } from "@adaas/a-server/server/A-Server.context";
+import { A_Error, A_Feature, A_Inject, A_Scope, } from "@adaas/a-concept";
 import { A_Request } from "@adaas/a-server/request/A-Request.entity";
 import { A_Response } from "@adaas/a-server/response/A-Response.entity";
 import { A_ResponseFeatures } from "@adaas/a-server/response/A-Response.constants";
@@ -69,9 +68,9 @@ export class A_ServerLogger extends A_Logger {
         scope: [A_Service]
     })
     logStop(
-        @A_Inject(A_Server) server: A_Server,
+        @A_Inject(A_Scope) scope: A_Scope,
     ) {
-        this.log('red', `Server ${server.name} stopped`);
+        this.info('red', `Server ${scope.name} stopped`);
     }
 
 

package/src/middlewares/A-ServerCORS/A_ServerCORS.component.ts

@@ -32,7 +32,7 @@ export class A_ServerCORS extends A_ServerMiddleware {
     }
 
 
-    @A_HttpServer.onAfterRequest
+    @A_HttpServer.onBeforeRequest
     public apply(
         @A_Inject(A_Request) aReq: A_Request,
         @A_Inject(A_Response) aRes: A_Response,