@nymphjs/nymph 1.0.0-beta.6 → 1.0.0-beta.61

package/dist/Entity.types.d.ts

@@ -1,14 +1,14 @@
 import type Nymph from './Nymph';
-import type { Options } from './Nymph.types';
+import type Entity from './Entity';
 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 EntityData = {
@@ -34,46 +34,252 @@ 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 the object from storage.
+     *
+     * @returns True on success, false on failure.
+     */
     $delete(): Promise<boolean>;
+    /**
+     * 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 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.
+     */
     $refresh(): Promise<boolean | 0>;
+    /**
+     * Save the object to storage.
+     *
+     * @returns True on success, false on failure.
+     */
     $save(): Promise<boolean>;
+    /**
+     * 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;
+    /**
+     * 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[];
+    /**
+     * 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.
+     * @returns The entity's data object.
+     */
     $getData(includeSData?: 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.
+     *
+     * 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.
+     *
+     * 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;
+    /**
+     * Used to set the data.
+     *
+     * This should only be used by Nymph to push the data from storage.
+     *
+     * `sdata` is used by Nymph to avoid unserializing data that hasn't been
+     * requested yet.
+     *
+     * @param data The data object.
+     * @param sdata The serialized data object.
+     */
     $putData(data: EntityData, sdata?: SerializedEntityData): void;
+    /**
+     * Remove one or more tags.
+     *
+     * @param tags List of tags.
+     */
     $removeTag(...tags: string[]): void;
+    /**
+     * 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;
+    /**
+     * 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];
 };