@nymphjs/client 1.0.0-beta.13 → 1.0.0-beta.131

package/src/Nymph.ts

@@ -1,24 +1,28 @@
-import Entity from './Entity';
-import {
+import Entity, { type EntityInstanceType } from './Entity.js';
+import type {
   EntityConstructor,
-  EntityData,
   EntityInterface,
   EntityJson,
   ServerCallResponse,
   ServerCallStaticResponse,
-} from './Entity.types';
-import EntityWeakCache from './EntityWeakCache';
-import HttpRequester from './HttpRequester';
-import {
+} from './Entity.types.js';
+import EntityWeakCache from './EntityWeakCache.js';
+import type { AbortableAsyncIterator } from './HttpRequester.js';
+import HttpRequester, { ClientError } from './HttpRequester.js';
+import type {
   EventType,
   NymphOptions,
   Options,
   RequestCallback,
   ResponseCallback,
   Selector,
-} from './Nymph.types';
-import PubSub from './PubSub';
-import { entitiesToReferences, entityConstructorsToClassNames } from './utils';
+} from './Nymph.types.js';
+import type PubSub from './PubSub.js';
+import {
+  classNamesToEntityConstructors,
+  entitiesToReferences,
+  entityConstructorsToClassNames,
+} from './utils.js';
 
 let requester: HttpRequester;
 
@@ -42,19 +46,42 @@ export default class Nymph {
   private responseCallbacks: ResponseCallback[] = [];
   private restUrl: string = '';
   private weakCache = false;
+  /**
+   * Headers that will be sent with every request.
+   *
+   * These are used by Tilmeld for authentication.
+   */
+  public headers: { [k: string]: string } = {};
+  /**
+   * The entity cache.
+   */
   public cache = new EntityWeakCache();
+  /**
+   * Return `null` or empty array instead of error when entity/ies not found.
+   */
+  public returnNullOnNotFound = false;
 
   public constructor(NymphOptions: NymphOptions) {
     this.restUrl = NymphOptions.restUrl;
     // @ts-ignore TS doesn't know about WeakRef.
     this.weakCache = !!NymphOptions.weakCache && typeof WeakRef !== 'undefined';
+    if (
+      'returnNullOnNotFound' in NymphOptions &&
+      NymphOptions.returnNullOnNotFound != null
+    ) {
+      this.returnNullOnNotFound = NymphOptions.returnNullOnNotFound;
+    }
 
     this.Entity = this.addEntityClass(Entity);
 
     requester = new HttpRequester(
-      'fetch' in NymphOptions ? NymphOptions.fetch : undefined
+      'fetch' in NymphOptions ? NymphOptions.fetch : undefined,
     );
 
+    if ('renewTokens' in NymphOptions && !NymphOptions.renewTokens) {
+      this.headers['X-Tilmeld-Token-Renewal'] = 'off';
+    }
+
     requester.on('request', (_requester, url, options) => {
       for (let i = 0; i < this.requestCallbacks.length; i++) {
         this.requestCallbacks[i] && this.requestCallbacks[i](url, options);
@@ -75,8 +102,9 @@ export default class Nymph {
    * Nymph and return it. You can then use this class's constructor and methods,
    * which will use this instance of Nymph.
    *
-   * Because this creates a subclass, don't use the class
-   * returned from `getEntityClass` to check with `instanceof`.
+   * Because this creates a subclass, don't use the class returned from
+   * `getEntityClass` to check with `instanceof`. Instead, use the base class
+   * that you passed into this method.
    */
   public addEntityClass<T extends EntityConstructor>(entityClass: T): T {
     const nymph = this;
@@ -91,18 +119,27 @@ export default class Nymph {
     return NymphEntity;
   }
 
-  public getEntityClass(className: string) {
-    if (className in this.entityClasses) {
-      return this.entityClasses[className];
+  public getEntityClass<T extends EntityConstructor>(className: T): T;
+  public getEntityClass(className: string): EntityConstructor;
+  public getEntityClass<T extends EntityConstructor = EntityConstructor>(
+    className: T | string,
+  ): T | EntityConstructor {
+    let key: string | null = null;
+    if (typeof className === 'string') {
+      key = className;
+    } else {
+      key = className.class;
     }
-    throw new ClassNotAvailableError(
-      "Tried to get class that's not available: " + className
-    );
+    if (key in this.entityClasses) {
+      return this.entityClasses[key];
+    }
+    throw new ClassNotAvailableError('Tried to use class: ' + key);
   }
 
   public async newUID(name: string) {
     const data = await requester.POST({
       url: this.restUrl,
+      headers: { ...this.headers },
       dataType: 'text',
       data: { action: 'uid', data: name },
     });
@@ -112,6 +149,7 @@ export default class Nymph {
   public async setUID(name: string, value: number) {
     return await requester.PUT({
       url: this.restUrl,
+      headers: { ...this.headers },
       dataType: 'json',
       data: { action: 'uid', data: { name, value } },
     });
@@ -120,6 +158,7 @@ export default class Nymph {
   public async getUID(name: string) {
     const data = await requester.GET({
       url: this.restUrl,
+      headers: { ...this.headers },
       dataType: 'text',
       data: { action: 'uid', data: name },
     });
@@ -129,6 +168,7 @@ export default class Nymph {
   public async deleteUID(name: string) {
     return await requester.DELETE({
       url: this.restUrl,
+      headers: { ...this.headers },
       dataType: 'text',
       data: { action: 'uid', data: name },
     });
@@ -152,7 +192,7 @@ export default class Nymph {
       ) {
         throw new InvalidRequestError(
           'Due to REST restriction, you can only create new entities or ' +
-            'update existing entities, not both at the same time.'
+            'update existing entities, not both at the same time.',
         );
       }
     });
@@ -162,7 +202,7 @@ export default class Nymph {
   public async patchEntity(entity: EntityInterface) {
     if (entity.guid == null) {
       throw new InvalidRequestError(
-        "You can't patch an entity that hasn't yet been saved."
+        "You can't patch an entity that hasn't yet been saved.",
       );
     }
 
@@ -179,7 +219,7 @@ export default class Nymph {
       if (cur.guid == null) {
         throw new InvalidRequestError(
           'Due to REST restriction, you can only create new entities or ' +
-            'update existing entities, not both at the same time.'
+            'update existing entities, not both at the same time.',
         );
       }
     });
@@ -191,22 +231,23 @@ export default class Nymph {
     entity: T,
     method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
     data: { [k: string]: any },
-    plural: false
+    plural: false,
   ): Promise<T>;
   private async requestWithMethod<T extends EntityInterface>(
     entity: T[],
     method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
     data: { [k: string]: any },
-    plural: true
+    plural: true,
   ): Promise<T[]>;
   private async requestWithMethod<T extends EntityInterface>(
     entity: T | T[],
     method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
     data: { [k: string]: any },
-    plural: boolean
+    plural: boolean,
   ): Promise<T | T[]> {
     const response = await requester[method]({
       url: this.restUrl,
+      headers: { ...this.headers },
       dataType: 'json',
       data: {
         action: plural ? 'entities' : 'entity',
@@ -216,12 +257,12 @@ export default class Nymph {
     if (plural && Array.isArray(entity) && entity.length === response.length) {
       return entity.map((e, i) =>
         response[i] &&
-        typeof response[i].guid !== 'undefined' &&
+        response[i].guid != null &&
         (e.guid == null || e.guid === response[i].guid)
           ? e.$init(response[i])
-          : e
+          : e,
       ) as T[];
-    } else if (!Array.isArray(entity) && typeof response.guid !== 'undefined') {
+    } else if (!Array.isArray(entity) && response.guid != null) {
       return entity.$init(response) as T;
     }
     throw new Error('Server error');
@@ -238,29 +279,39 @@ export default class Nymph {
   public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T>,
     ...selectors: Selector[]
-  ): Promise<ReturnType<T['factorySync']> | null>;
+  ): Promise<EntityInstanceType<T> | null>;
   public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T> & { return: 'count' },
-    guid: string
+    guid: string,
   ): Promise<number>;
   public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T> & { return: 'guid' },
-    guid: string
+    guid: string,
   ): Promise<string | null>;
   public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T>,
-    guid: string
-  ): Promise<ReturnType<T['factorySync']> | null>;
+    guid: string,
+  ): Promise<EntityInstanceType<T> | null>;
   public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T>,
     ...selectors: Selector[] | string[]
-  ): Promise<ReturnType<T['factorySync']> | string | number | null> {
-    // @ts-ignore: Implementation signatures of overloads are not externally visible.
-    const data = (await this.getEntityData(options, ...selectors)) as
-      | EntityJson<T>
-      | string
-      | number
-      | null;
+  ): Promise<EntityInstanceType<T> | string | number | null> {
+    let data: any = null;
+    try {
+      // @ts-ignore: Implementation signatures of overloads are not externally visible.
+      data = (await this.getEntityData(options, ...selectors)) as
+        EntityJson<T> | string | number | null;
+    } catch (e: any) {
+      if (
+        this.returnNullOnNotFound &&
+        e instanceof ClientError &&
+        e.status === 404
+      ) {
+        data = null;
+      } else {
+        throw e;
+      }
+    }
 
     if (options.return && options.return === 'count') {
       return Number(data ?? 0) as number;
@@ -290,23 +341,23 @@ export default class Nymph {
   ): Promise<EntityJson<T> | null>;
   public async getEntityData<T extends EntityConstructor = EntityConstructor>(
     options: Options<T> & { return: 'count' },
-    guid: string
+    guid: string,
   ): Promise<number>;
   public async getEntityData<T extends EntityConstructor = EntityConstructor>(
     options: Options<T> & { return: 'guid' },
-    guid: string
+    guid: string,
   ): Promise<string | null>;
   public async getEntityData<T extends EntityConstructor = EntityConstructor>(
     options: Options<T>,
-    guid: string
+    guid: string,
   ): Promise<EntityJson<T> | null>;
   public async getEntityData<T extends EntityConstructor = EntityConstructor>(
     options: Options<T>,
     ...selectors: Selector[] | string[]
   ): Promise<EntityJson<T> | string | number | null> {
-    if (options.class === this.getEntityClass('Entity')) {
+    if (options.class instanceof Entity) {
       throw new InvalidRequestError(
-        "You can't make REST requests with the base Entity class."
+        "You can't make REST requests with the base Entity class.",
       );
     }
     // Set up options and selectors.
@@ -315,12 +366,13 @@ export default class Nymph {
     }
     const data = await requester.GET({
       url: this.restUrl,
+      headers: { ...this.headers },
       dataType: 'json',
       data: {
         action: 'entity',
         data: [
-          { ...options, class: options.class.class },
-          ...entityConstructorsToClassNames(selectors),
+          entityConstructorsToClassNames(options),
+          ...entityConstructorsToClassNames(entitiesToReferences(selectors)),
         ],
       },
     });
@@ -342,25 +394,42 @@ export default class Nymph {
   public async getEntities<T extends EntityConstructor = EntityConstructor>(
     options: Options<T>,
     ...selectors: Selector[]
-  ): Promise<ReturnType<T['factorySync']>[]>;
+  ): Promise<EntityInstanceType<T>[]>;
   public async getEntities<T extends EntityConstructor = EntityConstructor>(
     options: Options<T>,
     ...selectors: Selector[]
-  ): Promise<ReturnType<T['factorySync']>[] | string[] | number> {
-    const data = await requester.GET({
-      url: this.restUrl,
-      dataType: 'json',
-      data: {
-        action: 'entities',
-        data: [
-          { ...options, class: options.class.class },
-          ...entityConstructorsToClassNames(selectors),
-        ],
-      },
-    });
+  ): Promise<EntityInstanceType<T>[] | string[] | number> {
+    let data = null;
+    try {
+      data = await requester.GET({
+        url: this.restUrl,
+        headers: { ...this.headers },
+        dataType: 'json',
+        data: {
+          action: 'entities',
+          data: [
+            entityConstructorsToClassNames(options),
+            ...entityConstructorsToClassNames(entitiesToReferences(selectors)),
+          ],
+        },
+      });
+    } catch (e: any) {
+      if (
+        this.returnNullOnNotFound &&
+        e instanceof ClientError &&
+        e.status === 404
+      ) {
+        data = null;
+      } else {
+        throw e;
+      }
+    }
 
     if (options.return && options.return === 'count') {
-      return Number(data);
+      return Number(data ?? 0) as number;
+    }
+    if (data == null) {
+      return [];
     }
     if (options.return && options.return === 'guid') {
       return data;
@@ -369,12 +438,15 @@ export default class Nymph {
   }
 
   public initEntity<T extends EntityConstructor = EntityConstructor>(
-    entityJSON: EntityJson<T>
-  ): ReturnType<T['factorySync']> {
-    const EntityClass = this.getEntityClass(entityJSON.class);
+    entityJSON: EntityJson<T>,
+  ): EntityInstanceType<T> {
+    const EntityClass = classNamesToEntityConstructors<T>(
+      this,
+      entityJSON.class as unknown as T,
+    );
     if (!EntityClass) {
       throw new ClassNotAvailableError(
-        entityJSON.class + ' class cannot be found.'
+        entityJSON.class + ' class cannot be found.',
       );
     }
     let entity = EntityClass.factorySync();
@@ -382,30 +454,28 @@ export default class Nymph {
       // Try to get it from cache.
       const entityFromCache = this.cache.get(
         EntityClass,
-        entityJSON.guid || ''
+        entityJSON.guid || '',
       );
       if (entityFromCache != null) {
-        entity = entityFromCache;
+        entity = entityFromCache as EntityInstanceType<T>;
       }
     }
-    return entity.$init(entityJSON) as ReturnType<T['factorySync']>;
+    return entity.$init(entityJSON) as EntityInstanceType<T>;
   }
 
   public getEntityFromCache<T extends EntityConstructor = EntityConstructor>(
     EntityClass: EntityConstructor,
-    guid: string
-  ): ReturnType<T['factorySync']> | null {
+    guid: string,
+  ): EntityInstanceType<T> | null {
     if (!this.weakCache) {
       return null;
     }
-    return this.cache.get(EntityClass, guid) as ReturnType<
-      T['factorySync']
-    > | null;
+    return this.cache.get(EntityClass, guid) as EntityInstanceType<T> | null;
   }
 
   public setEntityToCache(
     EntityClass: EntityConstructor,
-    entity: EntityInterface
+    entity: EntityInterface,
   ) {
     if (!this.weakCache) {
       return;
@@ -417,10 +487,7 @@ export default class Nymph {
     if (Array.isArray(item)) {
       // Recurse into lower arrays.
       return item.map((entry) => this.initEntitiesFromData(entry)) as T;
-    } else if (
-      item instanceof Object &&
-      !(item instanceof this.getEntityClass('Entity'))
-    ) {
+    } else if (item instanceof Object && !(item instanceof Entity)) {
       if (
         item.hasOwnProperty('class') &&
         item.hasOwnProperty('guid') &&
@@ -428,7 +495,10 @@ export default class Nymph {
         item.hasOwnProperty('mdate') &&
         item.hasOwnProperty('tags') &&
         item.hasOwnProperty('data') &&
-        this.getEntityClass((item as any as EntityJson).class)
+        classNamesToEntityConstructors(
+          this,
+          (item as any as EntityJson).class,
+        ) != null
       ) {
         return this.initEntity(item as any as EntityJson) as T;
       } else {
@@ -444,10 +514,11 @@ export default class Nymph {
 
   public async deleteEntity(
     entity: EntityInterface | EntityInterface[],
-    _plural = false
+    _plural = false,
   ) {
     return await requester.DELETE({
       url: this.restUrl,
+      headers: { ...this.headers },
       dataType: 'json',
       data: {
         action: _plural ? 'entities' : 'entity',
@@ -473,10 +544,11 @@ export default class Nymph {
     entity: EntityInterface,
     method: string,
     params: any[],
-    stateless = false
+    stateless = false,
   ): Promise<ServerCallResponse> {
     const data = await requester.POST({
       url: this.restUrl,
+      headers: { ...this.headers },
       dataType: 'json',
       data: {
         action: 'method',
@@ -484,7 +556,7 @@ export default class Nymph {
           entity,
           stateless,
           method,
-          params: entitiesToReferences(entityConstructorsToClassNames(params)),
+          params: entityConstructorsToClassNames(entitiesToReferences(params)),
         },
       },
     });
@@ -498,10 +570,11 @@ export default class Nymph {
   public async serverCallStatic(
     className: string,
     method: string,
-    params: any[]
+    params: any[],
   ): Promise<ServerCallStaticResponse> {
     const data = await requester.POST({
       url: this.restUrl,
+      headers: { ...this.headers },
       dataType: 'json',
       data: {
         action: 'method',
@@ -509,7 +582,7 @@ export default class Nymph {
           class: className,
           static: true,
           method: method,
-          params: entitiesToReferences(entityConstructorsToClassNames(params)),
+          params: entityConstructorsToClassNames(entitiesToReferences(params)),
         },
       },
     });
@@ -517,19 +590,57 @@ export default class Nymph {
     return this.initEntitiesFromData(data);
   }
 
+  public async serverCallStaticIterator(
+    className: string,
+    method: string,
+    params: any[],
+  ): Promise<AbortableAsyncIterator<ServerCallStaticResponse>> {
+    const iterable = await requester.POST_ITERATOR({
+      url: this.restUrl,
+      headers: { ...this.headers },
+      dataType: 'json',
+      data: {
+        action: 'method',
+        data: {
+          class: className,
+          static: true,
+          method: method,
+          iterator: true,
+          params: entityConstructorsToClassNames(entitiesToReferences(params)),
+        },
+      },
+    });
+
+    const that = this;
+    const iterator: AbortableAsyncIterator = {
+      abortController: iterable.abortController,
+      async *[Symbol.asyncIterator]() {
+        for await (let response of iterable) {
+          if (response instanceof Error) {
+            yield response;
+          } else {
+            yield that.initEntitiesFromData(response);
+          }
+        }
+      },
+    };
+
+    return iterator;
+  }
+
   public on<T extends EventType>(
     event: T,
     callback: T extends 'request'
       ? RequestCallback
       : T extends 'response'
-      ? ResponseCallback
-      : never
+        ? ResponseCallback
+        : never,
   ) {
     const prop = (event + 'Callbacks') as T extends 'request'
       ? 'requestCallbacks'
       : T extends 'request'
-      ? 'responseCallbacks'
-      : never;
+        ? 'responseCallbacks'
+        : never;
     if (!(prop in this)) {
       throw new Error('Invalid event type.');
     }
@@ -543,14 +654,14 @@ export default class Nymph {
     callback: T extends 'request'
       ? RequestCallback
       : T extends 'response'
-      ? ResponseCallback
-      : never
+        ? ResponseCallback
+        : never,
   ) {
     const prop = (event + 'Callbacks') as T extends 'request'
       ? 'requestCallbacks'
       : T extends 'request'
-      ? 'responseCallbacks'
-      : never;
+        ? 'responseCallbacks'
+        : never;
     if (!(prop in this)) {
       return false;
     }
@@ -562,10 +673,6 @@ export default class Nymph {
     }
     return true;
   }
-
-  public setXsrfToken(token: string | null) {
-    requester.setXsrfToken(token);
-  }
 }
 
 export class ClassNotAvailableError extends Error {