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

package/dist/Entity.types.d.ts

@@ -0,0 +1,216 @@
+import type Nymph from './Nymph.js';
+import type Entity from './Entity.js';
+export type ServerCallResponse = {
+    return: any;
+    entity?: EntityJson;
+};
+export type ServerCallStaticResponse = any;
+export type EntityReference = ['nymph_entity_reference', string, string];
+export type EntityData = {
+    [k: string]: any;
+};
+export type SerializedEntityData = {
+    [k: string]: string;
+};
+export type EntityJson<T extends EntityConstructor = EntityConstructor> = {
+    class: T['class'];
+    guid: string | null;
+    cdate: number | null;
+    mdate: number | null;
+    tags: string[];
+    data: EntityData;
+};
+export type EntityPatch = {
+    class: string;
+    guid: string;
+    mdate: number | null;
+    set: EntityData;
+    unset: string[];
+    addTags: string[];
+    removeTags: string[];
+};
+/**
+ * Data Object interface.
+ *
+ * Objects which hold data from some type of storage.
+ */
+export interface DataObjectInterface {
+    /**
+     * Search the array for this object and return the corresponding index.
+     *
+     * If `strict` is false, `is()` is used to compare. If `strict` is true,
+     * `equals()` is used.
+     *
+     * @param array The array to search.
+     * @param strict Whether to use stronger comparison.
+     * @returns The index if the object is in the array, -1 if it isn't.
+     */
+    $arraySearch(array: any[], strict?: boolean): number;
+    /**
+     * Delete the object from storage.
+     *
+     * An error is thrown on failure.
+     */
+    $delete(): Promise<void>;
+    /**
+     * Perform a more strict comparison of this object to another.
+     *
+     * @param object The object to compare.
+     * @returns True or false.
+     */
+    $equals(object: any): boolean;
+    /**
+     * Check whether this object is in an array.
+     *
+     * If `strict` is false, `is()` is used to compare. If `strict` is true,
+     * `equals()` is used.
+     *
+     * @param array The array to search.
+     * @param strict Whether to use stronger comparison.
+     * @returns True if the object is in the array, false if it isn't.
+     */
+    $inArray(array: any[], strict?: boolean): boolean;
+    /**
+     * Perform a less strict comparison of this object to another.
+     *
+     * @param object The object to compare.
+     * @returns True or false.
+     */
+    $is(object: any): boolean;
+    /**
+     * Save the object's dirty data to storage.
+     *
+     * An error is thrown on failure.
+     */
+    $patch(): Promise<void>;
+    /**
+     * Refresh the object from storage. (Bypasses Nymph's cache.)
+     *
+     * @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.
+     *
+     * An error is thrown on failure.
+     */
+    $save(): Promise<void>;
+    /**
+     * The object's data.
+     */
+    [k: string]: any;
+}
+/**
+ * Entity interface.
+ */
+export interface EntityInterface extends DataObjectInterface {
+    /**
+     * The instance of Nymph to use for queries.
+     */
+    $nymph: Nymph;
+    /**
+     * The entity's Globally Unique ID.
+     *
+     * This is a 12 byte number represented as a lower case HEX string (24
+     * characters).
+     */
+    guid: string | null;
+    /**
+     * The creation date of the entity as a Unix timestamp in milliseconds.
+     */
+    cdate: number | null;
+    /**
+     * The modified date of the entity as a Unix timestamp in milliseconds.
+     */
+    mdate: number | null;
+    /**
+     * Array of the entity's tags.
+     */
+    tags: string[];
+    /**
+     * Add one or more tags.
+     *
+     * @param tags List of tags.
+     */
+    $addTag(...tags: string[]): void;
+    /**
+     * Get a patch of this entity's dirty data to be applied on the server.
+     */
+    $getPatch(): EntityPatch;
+    /**
+     * Check that the entity has all of the given tags.
+     *
+     * @param tags List of tags.
+     * @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.
+     *
+     * @param entityJson The entity JSON.
+     */
+    $init(entityJson: EntityJson | null): EntityInterface;
+    /**
+     * Retrieve this entity's data from the server.
+     *
+     * @returns The entity.
+     */
+    $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 wake. If undefined, it will keep going until there are no more entities. (Careful of infinite loops.)
+     * @returns The entity.
+     */
+    $wakeAll(level?: number): Promise<EntityInterface>;
+    /**
+     * Remove one or more tags.
+     *
+     * @param tags List of tags.
+     */
+    $removeTag(...tags: string[]): void;
+    /**
+     * Call an instance method on the server version of this entity.
+     *
+     * The entity's data will be sent up to the server as well, so the server's
+     * state can match the client's state. It won't be propagated into the DB,
+     * though.
+     *
+     * @param method The name of the method.
+     * @param params The parameters to call the method with.
+     * @param stateless Whether the server should return, and the client update, the data in the entity after the method has run.
+     * @returns The value that the method on the server returned.
+     */
+    $serverCall(method: string, params: Iterable<any>, stateless: boolean): Promise<any>;
+    /**
+     * Return a Nymph Entity Reference for this entity.
+     *
+     * If the entity hasn't been saved yet (and has no GUID), it will be
+     * returned instead.
+     *
+     * @returns A Nymph Entity Reference array as an unsaved entity.
+     */
+    $toReference(): EntityReference | EntityInterface;
+}
+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/dist/Entity.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Entity.types.js.map

package/{lib → dist}/EntityWeakCache.d.ts

@@ -1,4 +1,4 @@
-import { EntityConstructor, EntityInterface } from './Entity.types';
+import { EntityConstructor, EntityInterface } from './Entity.types.js';
 export default class EntityWeakCache {
     private references;
     get(EntityClass: EntityConstructor, guid: string): EntityInterface | null;

package/{lib → dist}/EntityWeakCache.js

@@ -1,15 +1,12 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-class EntityWeakCache {
-    constructor() {
-        this.references = new WeakMap();
-    }
+export default class EntityWeakCache {
+    references = new WeakMap();
     get(EntityClass, guid) {
         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];
@@ -27,5 +24,4 @@ class EntityWeakCache {
         classMap[entity.guid] = weakRef;
     }
 }
-exports.default = EntityWeakCache;
 //# sourceMappingURL=EntityWeakCache.js.map

package/dist/EntityWeakCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityWeakCache.js","sourceRoot":"","sources":["../src/EntityWeakCache.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,OAAO,OAAO,eAAe;IAC1B,UAAU,GAGd,IAAI,OAAO,EAAE,CAAC;IAElB,GAAG,CAAC,WAA8B,EAAE,IAAY;QAC9C,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAClD,IAAI,QAAQ,IAAI,IAAI,IAAI,QAAQ,EAAE,CAAC;YACjC,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC/B,MAAM,KAAK,GAAG,OAAO,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YACzC,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;gBAClB,OAAO,KAAK,CAAC;YACf,CAAC;iBAAM,CAAC;gBACN,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,GAAG,CAAC,WAA8B,EAAE,MAAuB;QACzD,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACjB,OAAO;QACT,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;QAEpC,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;QACxD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;QAC3C,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;IAClC,CAAC;CACF"}

package/{lib → dist}/HttpRequester.d.ts

@@ -1,35 +1,49 @@
 export type HttpRequesterEventType = 'request' | 'response';
 export type HttpRequesterRequestCallback = (requester: HttpRequester, url: string, options: RequestInit) => void;
 export type HttpRequesterResponseCallback = (requester: HttpRequester, response: Response, 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;
-    private xsrfToken;
     private requestCallbacks;
     private responseCallbacks;
+    private iteratorCallbacks;
     static makeUrl(url: string, data: {
         [k: string]: any;
     }): string;
     constructor(ponyFetch?: WindowOrWorkerGlobalScope['fetch']);
-    on<T extends HttpRequesterEventType>(event: T, callback: T extends 'request' ? HttpRequesterRequestCallback : T extends 'response' ? HttpRequesterResponseCallback : never): () => boolean;
-    off<T extends HttpRequesterEventType>(event: T, callback: T extends 'request' ? HttpRequesterRequestCallback : T extends 'response' ? HttpRequesterResponseCallback : never): boolean;
-    setXsrfToken(xsrfToken: string | null): void;
+    on<T extends HttpRequesterEventType>(event: T, callback: T extends 'request' ? HttpRequesterRequestCallback : T extends 'response' ? HttpRequesterResponseCallback : T extends 'iterator' ? HttpRequesterIteratorCallback : never): () => boolean;
+    off<T extends HttpRequesterEventType>(event: T, callback: T extends 'request' ? HttpRequesterRequestCallback : T extends 'response' ? HttpRequesterResponseCallback : T extends 'iterator' ? HttpRequesterIteratorCallback : never): boolean;
     GET(opt: HttpRequesterRequestOptions): Promise<any>;
     POST(opt: HttpRequesterRequestOptions): Promise<any>;
+    POST_ITERATOR(opt: HttpRequesterRequestOptions): Promise<AbortableAsyncIterator<any>>;
     PUT(opt: HttpRequesterRequestOptions): Promise<any>;
     PATCH(opt: HttpRequesterRequestOptions): Promise<any>;
     DELETE(opt: HttpRequesterRequestOptions): Promise<any>;
     _httpRequest(method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', opt: HttpRequesterRequestOptions): Promise<any>;
+    _iteratorRequest(method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', opt: HttpRequesterRequestOptions): Promise<AbortableAsyncIterator>;
 }
 export declare class InvalidResponseError extends Error {
     constructor(message: string);
 }
+export declare class ConnectionClosedUnexpectedlyError extends Error {
+    constructor(message: string);
+}
+export declare class ConnectionError extends Error {
+    constructor(message: string);
+}
 export declare class HttpError extends Error {
     status: number;
     statusText: string;

package/dist/HttpRequester.js

@@ -0,0 +1,365 @@
+import { fetchEventSource, EventStreamContentType, } from 'fetch-event-source-hperrin';
+export default class HttpRequester {
+    fetch;
+    requestCallbacks = [];
+    responseCallbacks = [];
+    iteratorCallbacks = [];
+    static makeUrl(url, data) {
+        if (!data) {
+            return url;
+        }
+        for (let [key, value] of Object.entries(data)) {
+            url =
+                url +
+                    (url.indexOf('?') !== -1 ? '&' : '?') +
+                    encodeURIComponent(key) +
+                    '=' +
+                    encodeURIComponent(JSON.stringify(value));
+        }
+        return url;
+    }
+    constructor(ponyFetch) {
+        this.fetch = ponyFetch ? ponyFetch : (...args) => fetch(...args);
+    }
+    on(event, callback) {
+        const prop = (event + 'Callbacks');
+        if (!(prop in this)) {
+            throw new Error('Invalid event type.');
+        }
+        // @ts-ignore: The callback should always be the right type here.
+        this[prop].push(callback);
+        return () => this.off(event, callback);
+    }
+    off(event, callback) {
+        const prop = (event + 'Callbacks');
+        if (!(prop in this)) {
+            return false;
+        }
+        // @ts-ignore: The callback should always be the right type here.
+        const i = this[prop].indexOf(callback);
+        if (i > -1) {
+            // @ts-ignore: The callback should always be the right type here.
+            this[prop].splice(i, 1);
+        }
+        return true;
+    }
+    async GET(opt) {
+        return await this._httpRequest('GET', opt);
+    }
+    async POST(opt) {
+        return await this._httpRequest('POST', opt);
+    }
+    async POST_ITERATOR(opt) {
+        return await this._iteratorRequest('POST', opt);
+    }
+    async PUT(opt) {
+        return await this._httpRequest('PUT', opt);
+    }
+    async PATCH(opt) {
+        return await this._httpRequest('PATCH', opt);
+    }
+    async DELETE(opt) {
+        return await this._httpRequest('DELETE', opt);
+    }
+    async _httpRequest(method, opt) {
+        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 options = {
+            method,
+            headers: opt.headers ?? {},
+            credentials: 'include',
+        };
+        if (method !== 'GET' && opt.data) {
+            options.headers['Content-Type'] =
+                'application/json';
+            options.body = dataString;
+        }
+        for (let i = 0; i < this.requestCallbacks.length; i++) {
+            this.requestCallbacks[i] && this.requestCallbacks[i](this, url, options);
+        }
+        const response = await this.fetch(url, options);
+        let text;
+        try {
+            text = await response.text();
+        }
+        catch (e) {
+            throw new InvalidResponseError('Server response did not contain valid text body.');
+        }
+        if (!response.ok) {
+            let errObj;
+            try {
+                errObj = JSON.parse(text);
+            }
+            catch (e) {
+                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);
+        }
+        for (let i = 0; i < this.responseCallbacks.length; i++) {
+            this.responseCallbacks[i] &&
+                this.responseCallbacks[i](this, response, text);
+        }
+        if (opt.dataType === 'json') {
+            if (!text.length) {
+                throw new InvalidResponseError('Server response was empty.');
+            }
+            try {
+                return JSON.parse(text);
+            }
+            catch (e) {
+                if (!(e instanceof SyntaxError)) {
+                    throw e;
+                }
+                throw new InvalidResponseError('Server response was invalid: ' + JSON.stringify(text));
+            }
+        }
+        else {
+            return text;
+        }
+    }
+    async _iteratorRequest(method, opt) {
+        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 = 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 = [];
+        let nextResponseResolve;
+        let nextResponseReadyPromise = new Promise((res) => {
+            nextResponseResolve = res;
+        });
+        let responsesDone = false;
+        let serverResponse;
+        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 = '';
+                try {
+                    text = await response.text();
+                }
+                catch (e) {
+                    // Ignore error here.
+                }
+                let errObj;
+                try {
+                    errObj = JSON.parse(text);
+                }
+                catch (e) {
+                    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) {
+                                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) {
+                        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((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 = {
+            abortController: ctrl,
+            async *[Symbol.asyncIterator]() {
+                do {
+                    await nextResponseReadyPromise;
+                    while (responses.length) {
+                        yield responses.shift();
+                    }
+                } while (!responsesDone);
+            },
+        };
+        return iterator;
+    }
+}
+export class InvalidResponseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidResponseError';
+    }
+}
+export class ConnectionClosedUnexpectedlyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConnectionClosedUnexpectedlyError';
+    }
+}
+export class ConnectionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConnectionError';
+    }
+}
+export class HttpError extends Error {
+    status;
+    statusText;
+    constructor(name, response, errObj) {
+        super(errObj.textStatus);
+        this.name = name;
+        this.status = response.status;
+        this.statusText = response.statusText;
+        Object.assign(this, errObj);
+    }
+}
+export class InformationalError extends HttpError {
+    constructor(response, errObj) {
+        super('InformationalError', response, errObj);
+    }
+}
+export class SuccessError extends HttpError {
+    constructor(response, errObj) {
+        super('SuccessError', response, errObj);
+    }
+}
+export class RedirectError extends HttpError {
+    constructor(response, errObj) {
+        super('RedirectError', response, errObj);
+    }
+}
+export class ClientError extends HttpError {
+    constructor(response, errObj) {
+        super('ClientError', response, errObj);
+    }
+}
+export class ServerError extends HttpError {
+    constructor(response, errObj) {
+        super('ServerError', response, errObj);
+    }
+}
+//# sourceMappingURL=HttpRequester.js.map