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

package/src/Entity.types.ts

@@ -1,4 +1,5 @@
-import type Nymph from './Nymph';
+import type Nymph from './Nymph.js';
+import type Entity from './Entity.js';
 
 export type ServerCallResponse = {
   return: any;
@@ -56,9 +57,9 @@ export interface DataObjectInterface {
   /**
    * Delete the object from storage.
    *
-   * @returns True on success, false on failure.
+   * An error is thrown on failure.
    */
-  $delete(): Promise<boolean>;
+  $delete(): Promise<void>;
   /**
    * Perform a more strict comparison of this object to another.
    *
@@ -87,24 +88,22 @@ export interface DataObjectInterface {
   /**
    * Save the object's dirty data to storage.
    *
-   * @returns True on success, false on failure.
+   * An error is thrown on failure.
    */
-  $patch(): Promise<boolean>;
+  $patch(): Promise<void>;
   /**
    * Refresh the object from storage. (Bypasses Nymph's cache.)
    *
-   * If the object has been deleted from storage, the database cannot be
-   * reached, or a database error occurs, `refresh()` will return 0.
-   *
-   * @returns False if the data has not been saved, 0 if it can't be refreshed, true on success.
+   * @returns False if the data has not been saved, true on success. An error is
+   *          thrown on failure.
    */
   $refresh(): Promise<boolean | 0>;
   /**
    * Save the object to storage.
    *
-   * @returns True on success, false on failure.
+   * An error is thrown on failure.
    */
-  $save(): Promise<boolean>;
+  $save(): Promise<void>;
   /**
    * The object's data.
    */
@@ -155,6 +154,24 @@ export interface EntityInterface extends DataObjectInterface {
    * @returns True or false.
    */
   $hasTag(...tags: string[]): boolean;
+  /**
+   * Check whether a property is dirty.
+   *
+   * To be a dirty property, it must have been set or deleted since the entity
+   * was initialized. A clean property existed on initialization and hasn't been
+   * set or deleted. An untracked property didn't exist on initialization and
+   * hasn't been set or deleted.
+   *
+   * Note that this doesn't necessarily mean the property has changed. It could
+   * have been set to the same value, or created and then deleted.
+   *
+   * Entities are initialized when they are pulled from the server or saved.
+   * This is done with the `$init` method.
+   *
+   * @param property The name of a property.
+   * @returns True if it's dirty, false if not, and null if it's not tracked.
+   */
+  $isDirty(property: string): boolean | null;
   /**
    * Initialize this entity from a JSON representation.
    *
@@ -166,14 +183,14 @@ export interface EntityInterface extends DataObjectInterface {
    *
    * @returns The entity.
    */
-  $ready(): Promise<EntityInterface>;
+  $wake(): Promise<EntityInterface>;
   /**
    * Ready this entity's data, and the data of entity's within this one's.
    *
-   * @param level The number of levels deep to ready. If undefined, it will keep going until there are no more entities. (Careful of infinite loops.)
+   * @param level The number of levels deep to wake. If undefined, it will keep going until there are no more entities. (Careful of infinite loops.)
    * @returns The entity.
    */
-  $readyAll(level?: number): Promise<EntityInterface>;
+  $wakeAll(level?: number): Promise<EntityInterface>;
   /**
    * Remove one or more tags.
    *
@@ -195,7 +212,7 @@ export interface EntityInterface extends DataObjectInterface {
   $serverCall(
     method: string,
     params: Iterable<any>,
-    stateless: boolean
+    stateless: boolean,
   ): Promise<any>;
   /**
    * Return a Nymph Entity Reference for this entity.
@@ -208,46 +225,9 @@ export interface EntityInterface extends DataObjectInterface {
   $toReference(): EntityReference | EntityInterface;
 }
 
-export type EntityConstructor = (new (...args: any[]) => EntityInterface) & {
-  /**
-   * The instance of Nymph to use for queries.
-   */
-  nymph: Nymph;
-  /**
-   * The lookup name for this entity.
-   *
-   * This is used for reference arrays (and sleeping references) and client
-   * requests.
-   */
-  class: string;
-  /**
-   * Create a new entity instance.
-   *
-   * @param guid An optional GUID to retrieve.
-   */
-  factory(guid?: string): Promise<EntityInterface>;
-  /**
-   * Create a new entity instance.
-   *
-   * @param guid An optional GUID to retrieve.
-   */
-  factorySync(guid?: string): EntityInterface;
-  /**
-   * Create a new sleeping reference instance.
-   *
-   * Sleeping references won't retrieve their data from the server until they
-   * are readied with `ready()` or a parent's `readyAll()`.
-   *
-   * @param reference The Nymph Entity Reference to use to wake.
-   * @returns The new instance.
-   */
-  factoryReference(reference: EntityReference): EntityInterface;
-  /**
-   * Call a static method on the server version of this entity.
-   *
-   * @param method The name of the method.
-   * @param params The parameters to call the method with.
-   * @returns The value that the method on the server returned.
-   */
-  serverCallStatic(method: string, params: Iterable<any>): Promise<any>;
+export type EntityConstructor<
+  D extends EntityData = EntityData,
+  E extends Entity<D> = Entity<D>,
+> = (new (...args: any[]) => E) & {
+  [k in keyof typeof Entity]: (typeof Entity)[k];
 };

package/src/EntityWeakCache.ts

@@ -1,15 +1,18 @@
-import { EntityConstructor, EntityInterface } from './Entity.types';
+import { EntityConstructor, EntityInterface } from './Entity.types.js';
 
 export default class EntityWeakCache {
-  private references: WeakMap<EntityConstructor, { [k: string]: any }> =
-    new WeakMap();
+  private references: WeakMap<
+    EntityConstructor,
+    { [k: string]: WeakRef<EntityInterface> }
+  > = new WeakMap();
 
   get(EntityClass: EntityConstructor, guid: string): EntityInterface | null {
     const classMap = this.references.get(EntityClass);
     if (classMap && guid in classMap) {
       const weakRef = classMap[guid];
-      if (weakRef && weakRef.deref() != null) {
-        return weakRef.deref();
+      const deref = weakRef && weakRef.deref();
+      if (deref != null) {
+        return deref;
       } else {
         delete classMap[guid];
       }
@@ -22,7 +25,6 @@ export default class EntityWeakCache {
       return;
     }
 
-    // @ts-ignore TS doesn't know about WeakRef.
     const weakRef = new WeakRef(entity);
 
     const classMap = this.references.get(EntityClass) || {};

package/src/HttpRequester.ts

@@ -1,25 +1,42 @@
+import {
+  fetchEventSource,
+  EventStreamContentType,
+} from 'fetch-event-source-hperrin';
+
 export type HttpRequesterEventType = 'request' | 'response';
 export type HttpRequesterRequestCallback = (
   requester: HttpRequester,
   url: string,
-  options: RequestInit
+  options: RequestInit,
 ) => void;
 export type HttpRequesterResponseCallback = (
   requester: HttpRequester,
   response: Response,
-  text: string
+  text: string,
+) => void;
+export type HttpRequesterIteratorCallback = (
+  requester: HttpRequester,
+  url: string,
+  headers: Record<string, string>,
 ) => void;
 export type HttpRequesterRequestOptions = {
   url: string;
+  headers?: { [k: string]: any };
   data: { [k: string]: any };
   dataType: string;
 };
 
+export interface AbortableAsyncIterator<
+  T extends any = any,
+> extends AsyncIterable<T> {
+  abortController: AbortController;
+}
+
 export default class HttpRequester {
   private fetch: WindowOrWorkerGlobalScope['fetch'];
-  private xsrfToken: string | null = null;
   private requestCallbacks: HttpRequesterRequestCallback[] = [];
   private responseCallbacks: HttpRequesterResponseCallback[] = [];
+  private iteratorCallbacks: HttpRequesterIteratorCallback[] = [];
 
   static makeUrl(url: string, data: { [k: string]: any }) {
     if (!data) {
@@ -45,14 +62,18 @@ export default class HttpRequester {
     callback: T extends 'request'
       ? HttpRequesterRequestCallback
       : T extends 'response'
-      ? HttpRequesterResponseCallback
-      : never
+        ? HttpRequesterResponseCallback
+        : T extends 'iterator'
+          ? HttpRequesterIteratorCallback
+          : never,
   ) {
     const prop = (event + 'Callbacks') as T extends 'request'
       ? 'requestCallbacks'
       : T extends 'response'
-      ? 'responseCallbacks'
-      : never;
+        ? 'responseCallbacks'
+        : T extends 'iterator'
+          ? 'iteratorCallbacks'
+          : never;
     if (!(prop in this)) {
       throw new Error('Invalid event type.');
     }
@@ -66,14 +87,18 @@ export default class HttpRequester {
     callback: T extends 'request'
       ? HttpRequesterRequestCallback
       : T extends 'response'
-      ? HttpRequesterResponseCallback
-      : never
+        ? HttpRequesterResponseCallback
+        : T extends 'iterator'
+          ? HttpRequesterIteratorCallback
+          : never,
   ) {
     const prop = (event + 'Callbacks') as T extends 'request'
       ? 'requestCallbacks'
       : T extends 'response'
-      ? 'responseCallbacks'
-      : never;
+        ? 'responseCallbacks'
+        : T extends 'iterator'
+          ? 'iteratorCallbacks'
+          : never;
     if (!(prop in this)) {
       return false;
     }
@@ -86,10 +111,6 @@ export default class HttpRequester {
     return true;
   }
 
-  setXsrfToken(xsrfToken: string | null) {
-    this.xsrfToken = xsrfToken;
-  }
-
   async GET(opt: HttpRequesterRequestOptions) {
     return await this._httpRequest('GET', opt);
   }
@@ -98,6 +119,10 @@ export default class HttpRequester {
     return await this._httpRequest('POST', opt);
   }
 
+  async POST_ITERATOR(opt: HttpRequesterRequestOptions) {
+    return await this._iteratorRequest('POST', opt);
+  }
+
   async PUT(opt: HttpRequesterRequestOptions) {
     return await this._httpRequest('PUT', opt);
   }
@@ -112,7 +137,7 @@ export default class HttpRequester {
 
   async _httpRequest(
     method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
-    opt: HttpRequesterRequestOptions
+    opt: HttpRequesterRequestOptions,
   ) {
     const dataString = JSON.stringify(opt.data);
     let url = opt.url;
@@ -123,7 +148,7 @@ export default class HttpRequester {
     }
     const options: RequestInit = {
       method,
-      headers: {},
+      headers: opt.headers ?? {},
       credentials: 'include',
     };
 
@@ -137,18 +162,13 @@ export default class HttpRequester {
       this.requestCallbacks[i] && this.requestCallbacks[i](this, url, options);
     }
 
-    if (this.xsrfToken !== null) {
-      (options.headers as Record<string, string>)['X-Xsrf-Token'] =
-        this.xsrfToken;
-    }
-
     const response = await this.fetch(url, options);
     let text: string;
     try {
       text = await response.text();
     } catch (e: any) {
       throw new InvalidResponseError(
-        'Server response did not contain valid text body.'
+        'Server response did not contain valid text body.',
       );
     }
     if (!response.ok) {
@@ -170,12 +190,12 @@ export default class HttpRequester {
       throw response.status < 200
         ? new InformationalError(response, errObj)
         : response.status < 300
-        ? new SuccessError(response, errObj)
-        : response.status < 400
-        ? new RedirectError(response, errObj)
-        : response.status < 500
-        ? new ClientError(response, errObj)
-        : new ServerError(response, errObj);
+          ? new SuccessError(response, errObj)
+          : response.status < 400
+            ? new RedirectError(response, errObj)
+            : response.status < 500
+              ? new ClientError(response, errObj)
+              : new ServerError(response, errObj);
     }
     for (let i = 0; i < this.responseCallbacks.length; i++) {
       this.responseCallbacks[i] &&
@@ -192,13 +212,216 @@ export default class HttpRequester {
           throw e;
         }
         throw new InvalidResponseError(
-          'Server response was invalid: ' + JSON.stringify(text)
+          'Server response was invalid: ' + JSON.stringify(text),
         );
       }
     } else {
       return text;
     }
   }
+
+  async _iteratorRequest(
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+    opt: HttpRequesterRequestOptions,
+  ): Promise<AbortableAsyncIterator> {
+    const dataString = JSON.stringify(opt.data);
+    let url = opt.url;
+    if (method === 'GET') {
+      // TODO: what should this size be?
+      // && dataString.length < 1) {
+      url = HttpRequester.makeUrl(opt.url, opt.data);
+    }
+    const hasBody = method !== 'GET' && opt.data;
+    const headers: Record<string, string> = opt.headers ?? {};
+
+    if (hasBody) {
+      headers['Content-Type'] = 'application/json';
+    }
+
+    for (let i = 0; i < this.iteratorCallbacks.length; i++) {
+      this.iteratorCallbacks[i] &&
+        this.iteratorCallbacks[i](this, url, headers);
+    }
+
+    const responses: any[] = [];
+    let nextResponseResolve: (value: void) => void;
+    let nextResponseReadyPromise = new Promise<void>((res) => {
+      nextResponseResolve = res;
+    });
+    let responsesDone = false;
+    let serverResponse: Response;
+
+    const ctrl = new AbortController();
+
+    fetchEventSource(url, {
+      openWhenHidden: true,
+      fetch: this.fetch,
+
+      method,
+      headers,
+      credentials: 'include',
+      body: hasBody ? dataString : undefined,
+      signal: ctrl.signal,
+
+      async onopen(response) {
+        serverResponse = response;
+        if (response.ok) {
+          if (response.headers.get('content-type') === EventStreamContentType) {
+            throw new InvalidResponseError(
+              'Server response is not an event stream.',
+            );
+          }
+
+          // Response is ok, wait for messages.
+          return;
+        }
+
+        let text: string = '';
+        try {
+          text = await response.text();
+        } catch (e: any) {
+          // Ignore error here.
+        }
+
+        let errObj;
+        try {
+          errObj = JSON.parse(text);
+        } catch (e: any) {
+          if (!(e instanceof SyntaxError)) {
+            throw e;
+          }
+        }
+
+        if (typeof errObj !== 'object') {
+          errObj = {
+            textStatus: response.statusText,
+          };
+        }
+        errObj.status = response.status;
+        throw response.status < 200
+          ? new InformationalError(response, errObj)
+          : response.status < 300
+            ? new SuccessError(response, errObj)
+            : response.status < 400
+              ? new RedirectError(response, errObj)
+              : response.status < 500
+                ? new ClientError(response, errObj)
+                : new ServerError(response, errObj);
+      },
+
+      onmessage(event) {
+        if (event.event === 'next') {
+          let text = event.data;
+
+          if (opt.dataType === 'json') {
+            if (!text.length) {
+              responses.push(
+                new InvalidResponseError('Server response was empty.'),
+              );
+            } else {
+              try {
+                responses.push(JSON.parse(text));
+              } catch (e: any) {
+                if (!(e instanceof SyntaxError)) {
+                  responses.push(e);
+                } else {
+                  responses.push(
+                    new InvalidResponseError(
+                      'Server response was invalid: ' + JSON.stringify(text),
+                    ),
+                  );
+                }
+              }
+            }
+          } else {
+            responses.push(text);
+          }
+        } else if (event.event === 'error') {
+          let text = event.data;
+
+          let errObj;
+          try {
+            errObj = JSON.parse(text);
+          } catch (e: any) {
+            if (!(e instanceof SyntaxError)) {
+              throw e;
+            }
+          }
+
+          if (typeof errObj !== 'object') {
+            errObj = {
+              status: 500,
+              textStatus: 'Iterator Error',
+            };
+          }
+          responses.push(
+            errObj.status < 200
+              ? new InformationalError(serverResponse, errObj)
+              : errObj.status < 300
+                ? new SuccessError(serverResponse, errObj)
+                : errObj.status < 400
+                  ? new RedirectError(serverResponse, errObj)
+                  : errObj.status < 500
+                    ? new ClientError(serverResponse, errObj)
+                    : new ServerError(serverResponse, errObj),
+          );
+        } else if (event.event === 'finished') {
+          responsesDone = true;
+        } else if (event.event === 'ping') {
+          // Ignore keep-alive pings.
+          return;
+        }
+
+        const resolve = nextResponseResolve;
+        if (!responsesDone) {
+          nextResponseReadyPromise = new Promise<void>((res) => {
+            nextResponseResolve = res;
+          });
+        }
+
+        // Resolve the promise to continue any waiting iterator.
+        resolve();
+      },
+
+      onclose() {
+        responses.push(
+          new ConnectionClosedUnexpectedlyError(
+            'The connection to the server was closed unexpectedly.',
+          ),
+        );
+
+        responsesDone = true;
+        nextResponseResolve();
+      },
+
+      onerror(err) {
+        // Rethrow to stop the operation.
+        throw err;
+      },
+    }).catch((err) => {
+      responses.push(
+        new ConnectionError('The connection could not be established: ' + err),
+      );
+
+      responsesDone = true;
+      nextResponseResolve();
+    });
+
+    const iterator: AbortableAsyncIterator = {
+      abortController: ctrl,
+      async *[Symbol.asyncIterator]() {
+        do {
+          await nextResponseReadyPromise;
+
+          while (responses.length) {
+            yield responses.shift();
+          }
+        } while (!responsesDone);
+      },
+    };
+
+    return iterator;
+  }
 }
 
 export class InvalidResponseError extends Error {
@@ -208,6 +431,20 @@ export class InvalidResponseError extends Error {
   }
 }
 
+export class ConnectionClosedUnexpectedlyError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ConnectionClosedUnexpectedlyError';
+  }
+}
+
+export class ConnectionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ConnectionError';
+  }
+}
+
 export class HttpError extends Error {
   status: number;
   statusText: string;
@@ -215,7 +452,7 @@ export class HttpError extends Error {
   constructor(
     name: string,
     response: Response,
-    errObj: { textStatus: string }
+    errObj: { textStatus: string },
   ) {
     super(errObj.textStatus);
     this.name = name;