@nymphjs/client 1.0.0-beta.9 → 1.0.0-beta.91

package/src/Nymph.ts

@@ -1,24 +1,27 @@
-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 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 {
+  entitiesToReferences,
+  entityConstructorsToClassNames,
+} from './utils.js';
 
 let requester: HttpRequester;
 
@@ -42,6 +45,15 @@ 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();
 
   public constructor(NymphOptions: NymphOptions) {
@@ -52,9 +64,13 @@ export default class Nymph {
     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 +91,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 +108,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 +138,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 +147,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 +157,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 +181,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 +191,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 +208,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 +220,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',
@@ -219,7 +249,7 @@ export default class Nymph {
         typeof response[i].guid !== 'undefined' &&
         (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') {
       return entity.$init(response) as T;
@@ -238,23 +268,23 @@ 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> {
+  ): Promise<EntityInstanceType<T> | string | number | null> {
     // @ts-ignore: Implementation signatures of overloads are not externally visible.
     const data = (await this.getEntityData(options, ...selectors)) as
       | EntityJson<T>
@@ -290,23 +320,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,6 +345,7 @@ export default class Nymph {
     }
     const data = await requester.GET({
       url: this.restUrl,
+      headers: { ...this.headers },
       dataType: 'json',
       data: {
         action: 'entity',
@@ -342,13 +373,14 @@ 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> {
+  ): Promise<EntityInstanceType<T>[] | string[] | number> {
     const data = await requester.GET({
       url: this.restUrl,
+      headers: { ...this.headers },
       dataType: 'json',
       data: {
         action: 'entities',
@@ -369,12 +401,12 @@ export default class Nymph {
   }
 
   public initEntity<T extends EntityConstructor = EntityConstructor>(
-    entityJSON: EntityJson<T>
-  ): ReturnType<T['factorySync']> {
+    entityJSON: EntityJson<T>,
+  ): EntityInstanceType<T> {
     const EntityClass = this.getEntityClass(entityJSON.class);
     if (!EntityClass) {
       throw new ClassNotAvailableError(
-        entityJSON.class + ' class cannot be found.'
+        entityJSON.class + ' class cannot be found.',
       );
     }
     let entity = EntityClass.factorySync();
@@ -382,30 +414,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 +447,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') &&
@@ -444,10 +471,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 +501,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',
@@ -498,10 +527,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',
@@ -517,19 +547,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: entitiesToReferences(entityConstructorsToClassNames(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 +611,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 +630,6 @@ export default class Nymph {
     }
     return true;
   }
-
-  public setXsrfToken(token: string | null) {
-    requester.setXsrfToken(token);
-  }
 }
 
 export class ClassNotAvailableError extends Error {

package/src/Nymph.types.ts

@@ -1,4 +1,4 @@
-import { EntityConstructor, EntityInterface } from './Entity.types';
+import { EntityConstructor, EntityInterface } from './Entity.types.js';
 
 export type NymphOptions = {
   /**
@@ -21,6 +21,10 @@ export type NymphOptions = {
    * Whether to not output status messages to the console.
    */
   noConsole?: boolean;
+  /**
+   * Don't automatically try to connect to PubSub server.
+   */
+  noAutoconnect?: boolean;
   /**
    * Use a WeakRef based cache of entities.
    *
@@ -40,6 +44,16 @@ export type NymphOptions = {
    * can help to synchronize them correctly and avoid data conflicts.
    */
   weakCache?: boolean;
+  /**
+   * Whether to renew tokens when a request is made.
+   *
+   * If you turn this off, the client will request that the server not renew an
+   * authentication token, even if it is within the renewal time of the
+   * expiration date.
+   *
+   * This defaults to true.
+   */
+  renewTokens?: boolean;
 };
 
 export type EventType = 'request' | 'response';
@@ -49,12 +63,37 @@ export type RequestCallback = (url: string, options: RequestInit) => void;
 export type ResponseCallback = (response: Response, text: string) => void;
 
 export type Options<T extends EntityConstructor = EntityConstructor> = {
+  /**
+   * The Entity class to query.
+   */
   class: T;
+  /**
+   * The limit of entities to be returned. Not needed when using `getEntity`, as
+   * it always returns only one.
+   */
   limit?: number;
+  /**
+   * The offset from the first matching entity, in order, to start retrieving.
+   */
   offset?: number;
+  /**
+   * If true, entities will be retrieved from newest to oldest/largest to
+   * smallest (with regard to `sort`).
+   */
   reverse?: boolean;
-  sort?: 'cdate' | 'mdate';
+  /**
+   * How to sort the entities. Should be "cdate", "mdate", or the name of a
+   * property.
+   */
+  sort?: 'cdate' | 'mdate' | string;
+  /**
+   * What to return, the entities with their data, just the GUIDs, or just a
+   * count.
+   */
   return?: 'entity' | 'guid' | 'count';
+  /**
+   * If true, Nymph will skip the cache and retrieve the entity from the DB.
+   */
   skipCache?: boolean;
 };