@nymphjs/client 1.0.0-beta.1 → 1.0.0-beta.100

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, { 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 {
+  entitiesToReferences,
+  entityConstructorsToClassNames,
+} from './utils.js';
 
 let requester: HttpRequester;
 
@@ -36,28 +39,48 @@ export default class Nymph {
   /**
    * The entity class for this instance of Nymph.
    */
-  public Entity: typeof Entity = Entity;
+  public Entity: typeof Entity;
 
   private requestCallbacks: RequestCallback[] = [];
   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;
+    }
 
-    class NymphEntity<T extends EntityData = EntityData> extends Entity<T> {}
-    NymphEntity.nymph = this;
-    this.Entity = NymphEntity;
-    this.addEntityClass(NymphEntity);
+    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);
@@ -71,25 +94,51 @@ export default class Nymph {
     });
   }
 
-  public addEntityClass(entityClass: EntityConstructor) {
-    this.entityClasses[entityClass.class] = entityClass;
-    entityClass.nymph = this;
+  /**
+   * Add your class to this instance.
+   *
+   * This will create a class that extends your class within this instance of
+   * 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`. Instead, use the base class
+   * that you passed into this method.
+   */
+  public addEntityClass<T extends EntityConstructor>(entityClass: T): T {
+    const nymph = this;
+    class NymphEntity extends entityClass {
+      static nymph: Nymph = nymph;
+
+      constructor(...args: any[]) {
+        super(...args);
+      }
+    }
+    this.entityClasses[entityClass.class] = NymphEntity;
+    return NymphEntity;
   }
 
-  public getEntityClass(className: string) {
-    if (this.entityClasses.hasOwnProperty(className)) {
-      const EntityClass = this.entityClasses[className];
-      EntityClass.nymph = this;
-      return EntityClass;
+  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 },
     });
@@ -99,6 +148,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 } },
     });
@@ -107,6 +157,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 },
     });
@@ -116,6 +167,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 },
     });
@@ -139,7 +191,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.',
         );
       }
     });
@@ -149,7 +201,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.",
       );
     }
 
@@ -166,7 +218,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.',
         );
       }
     });
@@ -178,22 +230,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',
@@ -206,7 +259,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;
@@ -225,29 +278,42 @@ 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;
@@ -277,23 +343,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.
@@ -302,6 +368,7 @@ export default class Nymph {
     }
     const data = await requester.GET({
       url: this.restUrl,
+      headers: { ...this.headers },
       dataType: 'json',
       data: {
         action: 'entity',
@@ -329,25 +396,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: [
+            { ...options, class: options.class.class },
+            ...entityConstructorsToClassNames(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;
@@ -356,12 +440,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();
@@ -369,30 +453,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;
@@ -404,10 +486,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') &&
@@ -431,10 +510,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',
@@ -460,10 +540,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',
@@ -485,10 +566,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',
@@ -504,19 +586,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.');
     }
@@ -530,14 +650,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;
     }
@@ -549,10 +669,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 = {
   /**
@@ -17,10 +17,18 @@ export type NymphOptions = {
    * A WebSocket implementation.
    */
   WebSocket?: typeof WebSocket;
+  /**
+   * Return `null` or empty array instead of error when entity/ies not found.
+   */
+  returnNullOnNotFound?: boolean;
   /**
    * 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 +48,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 +67,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;
 };
 
@@ -81,6 +124,9 @@ type PrimitiveSelector = {
   contain?: [string, any];
   '!contain'?: PrimitiveSelector['contain'];
 
+  search?: [string, string];
+  '!search'?: PrimitiveSelector['search'];
+
   match?: [string, string];
   '!match'?: PrimitiveSelector['match'];
 
@@ -136,6 +182,9 @@ export type Selector = {
   contain?: Clause<OrWithTime<PrimitiveSelector['contain']>>;
   '!contain'?: Clause<OrWithTime<PrimitiveSelector['contain']>>;
 
+  search?: Clause<PrimitiveSelector['search']>;
+  '!search'?: Clause<PrimitiveSelector['search']>;
+
   match?: Clause<PrimitiveSelector['match']>;
   '!match'?: Clause<PrimitiveSelector['match']>;