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

package/dist/Entity.types.d.ts

@@ -1,24 +1,32 @@
-import type Nymph from './Nymph';
-import type { Options } from './Nymph.types';
+import type Nymph from './Nymph.js';
+import type Entity from './Entity.js';
 export type ACProperties = {
-    user: any;
-    group: any;
-    acUser: any;
-    acGroup: any;
-    acOther: any;
-    acRead: any;
-    acWrite: any;
-    acFull: any;
+    user: string | null;
+    group: string | null;
+    acUser: number | null;
+    acGroup: number | null;
+    acOther: number | null;
+    acRead: (string | null)[] | null;
+    acWrite: (string | null)[] | null;
+    acFull: (string | null)[] | null;
 };
 export type EntityReference = ['nymph_entity_reference', string, string];
+export type ClassReference = ['nymph_class_reference', string];
 export type EntityData = {
     [k: string]: any;
 };
 export type SerializedEntityData = {
     [k: string]: string;
 };
+export type EntityObject = {
+    guid: string | null;
+    cdate: number | null;
+    mdate: number | null;
+    tags: string[];
+    [k: string]: any;
+};
 export type EntityJson = {
-    class: string;
+    class: EntityConstructor;
     guid: string | null;
     cdate: number | null;
     mdate: number | null;
@@ -26,7 +34,7 @@ export type EntityJson = {
     data: EntityData;
 };
 export type EntityPatch = {
-    class: string;
+    class: EntityConstructor;
     guid: string;
     mdate: number | null;
     set: EntityData;
@@ -34,46 +42,285 @@ export type EntityPatch = {
     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(): Promise<boolean>;
+    /**
+     * 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;
-    $refresh(): Promise<boolean | 0>;
-    $save(): Promise<boolean>;
+    /**
+     * 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>;
+    /**
+     * 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[];
+    /**
+     * Get a GUID for the entity.
+     *
+     * If the entity has already been saved, this will just return the GUID.
+     *
+     * If the entity has not yet been saved, this will return a new GUID that gets
+     * held by the entity. The `guid` property will remain null, but this method
+     * will then always return the same GUID. When the entity is eventually saved
+     * into the database, this GUID will be used.
+     */
+    $getGuaranteedGUID(): string;
+    /**
+     * Add one or more tags.
+     *
+     * @param tags List of tags.
+     */
     $addTag(...tags: string[]): void;
+    /**
+     * Replace any referenced entities in the data with sleeping references.
+     *
+     * Calling this function ensures that the next time a referenced entity is
+     * accessed, it will be retrieved from the DB (unless it is in Nymph's cache).
+     */
     $clearCache(): void;
+    /**
+     * Get the client enabled methods.
+     *
+     * @returns The names of methods allowed to be called by the frontend with
+     *          serverCall.
+     */
     $getClientEnabledMethods(): string[];
-    $getData(includeSData?: boolean): EntityData;
+    /**
+     * Used to retrieve the data object.
+     *
+     * This should only be used by Nymph to save the data into storage.
+     *
+     * @param includeSData Whether to include the serialized data as well.
+     * @param referenceOnlyExisting Whether to only turn existing entities into
+     *                              references.
+     * @returns The entity's data object.
+     */
+    $getData(includeSData?: boolean, referenceOnlyExisting?: boolean): EntityData;
+    /**
+     * Used to retrieve the serialized data object.
+     *
+     * This should only be used by Nymph to save the data object into storage.
+     *
+     * This method is used by Nymph to avoid unserializing data that hasn't been
+     * requested yet.
+     *
+     * It should always be called after getData().
+     *
+     * @returns The entity's serialized data object.
+     */
     $getSData(): SerializedEntityData;
+    /**
+     * Get an array of strings that **must** be unique across the current etype.
+     *
+     * When you try to save another entity with any of the same unique strings,
+     * Nymph will throw an error.
+     *
+     * The default implementation of this method returns an empty array, meaning
+     * there are no uniqueness constraints applied to its etype.
+     *
+     * @returns Resolves to an array of entity's unique constraint strings.
+     */
+    $getUniques(): Promise<string[]>;
+    /**
+     * Get the original values of the AC properties.
+     *
+     * @returns An object of AC properties.
+     */
     $getOriginalAcValues(): ACProperties;
+    /**
+     * Get the current values of the AC properties.
+     *
+     * @returns An object of AC properties.
+     */
+    $getCurrentAcValues(): ACProperties;
+    /**
+     * Get an object that holds the same data as the entity.
+     *
+     * This provides an object that can be validated.
+     *
+     * @returns A pure object representation of the entity.
+     */
     $getValidatable(): Object;
+    /**
+     * Get the entity's tags.
+     *
+     * Using this instead of accessing the `tags` prop directly will wake sleeping
+     * references.
+     *
+     * @returns The entity's tags.
+     */
     $getTags(): string[];
+    /**
+     * Check that the entity has all of the given tags.
+     *
+     * @param tags List of tags.
+     * @returns True or false.
+     */
     $hasTag(...tags: string[]): boolean;
+    /**
+     * Accept JSON data from the client.
+     *
+     * The given data must already be dereferenced (class references turned into
+     * classes and entity references turned into entities).
+     *
+     * This function uses the security protection lists:
+     *
+     * - $protectedTags
+     * - $protectedData
+     * - $allowlistTags
+     * - $allowlistData
+     *
+     * @param input The input data. Please note, this will be modified
+     *              (destroyed).
+     * @param allowConflict Allow to accept data that is older than the current
+     *                      data.
+     */
     $jsonAcceptData(input: EntityJson, allowConflict?: boolean): void;
+    /**
+     * Accept JSON patch from the client.
+     *
+     * The given data must already be dereferenced (class references turned into
+     * classes and entity references turned into entities).
+     *
+     * This function uses the security protection lists:
+     *
+     * - $protectedTags
+     * - $protectedData
+     * - $allowlistTags
+     * - $allowlistData
+     *
+     * @param patch The patch data. Please note, this will be modified
+     *              (destroyed).
+     * @param allowConflict Allow to accept data that is older than the current
+     *                      data.
+     */
     $jsonAcceptPatch(patch: EntityPatch, allowConflict?: boolean): void;
-    $putData(data: EntityData, sdata?: SerializedEntityData): void;
+    /**
+     * Used to set the data.
+     *
+     * This should only be used by Nymph to push the data from storage or the
+     * client.
+     *
+     * The given data must already be dereferenced (class references turned into
+     * classes and entity references turned into entities).
+     *
+     * `sdata` is used by Nymph to avoid unserializing data that hasn't been
+     * requested yet.
+     *
+     * If `source` is set to "server", the data is coming from the DB or the
+     * cache. If not, assume the data is coming from the client and can't be
+     * trusted.
+     *
+     * @param data The data object.
+     * @param sdata The serialized data object.
+     * @param source If this is set to "server", the data is coming from the DB.
+     */
+    $putData(data: EntityData, sdata?: SerializedEntityData, source?: 'server'): void;
+    /**
+     * Remove one or more tags.
+     *
+     * @param tags List of tags.
+     */
     $removeTag(...tags: string[]): void;
-    $toReference(): EntityReference | EntityInterface;
+    /**
+     * Return a Nymph Entity Reference for this entity.
+     *
+     * If the entity hasn't been saved yet (and has no GUID), it will use the
+     * guaranteed GUID from `$getGuaranteedGUID`, unless `existingOnly` is true,
+     * then it will return the entity.
+     *
+     * @param existingOnly Whether to only turn existing entities into references.
+     * @returns A Nymph Entity Reference array.
+     */
+    $toReference(existingOnly?: boolean): EntityReference | EntityInterface;
+    /**
+     * Set whether to use "skipAc" when accessing entity references.
+     *
+     * @param useSkipAc True or false, whether to use it.
+     */
     $useSkipAc(useSkipAc: boolean): void;
 }
-export type EntityConstructor = (new (...args: any[]) => EntityInterface) & {
-    nymph: Nymph;
-    ETYPE: string;
-    class: string;
-    searchRestrictedData: string[];
-    clientEnabledStaticMethods: string[];
-    factory(guid?: string): Promise<EntityInterface>;
-    factorySync(guid?: string): EntityInterface;
-    factoryReference(reference: EntityReference): EntityInterface;
-    alterOptions?<T extends Options>(options: T): T;
+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

@@ -1,3 +1,2 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};
 //# sourceMappingURL=Entity.types.js.map