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

package/src/Entity.types.ts

@@ -1,18 +1,19 @@
-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;
@@ -22,8 +23,16 @@ 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;
@@ -32,7 +41,7 @@ export type EntityJson = {
 };
 
 export type EntityPatch = {
-  class: string;
+  class: EntityConstructor;
   guid: string;
   mdate: number | null;
   set: EntityData;
@@ -61,9 +70,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.
    *
@@ -92,18 +101,16 @@ export interface DataObjectInterface {
   /**
    * 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>;
+  $refresh(): Promise<boolean>;
   /**
    * 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.
    */
@@ -137,6 +144,17 @@ export interface EntityInterface extends DataObjectInterface {
    * 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.
    *
@@ -153,7 +171,8 @@ export interface EntityInterface extends DataObjectInterface {
   /**
    * Get the client enabled methods.
    *
-   * @returns The names of methods allowed to be called by the frontend with serverCall.
+   * @returns The names of methods allowed to be called by the frontend with
+   *          serverCall.
    */
   $getClientEnabledMethods(): string[];
   /**
@@ -162,9 +181,11 @@ export interface EntityInterface extends DataObjectInterface {
    * 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): EntityData;
+  $getData(includeSData?: boolean, referenceOnlyExisting?: boolean): EntityData;
   /**
    * Used to retrieve the serialized data object.
    *
@@ -178,12 +199,30 @@ export interface EntityInterface extends DataObjectInterface {
    * @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.
    *
@@ -211,6 +250,9 @@ export interface EntityInterface extends DataObjectInterface {
   /**
    * 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
@@ -218,13 +260,18 @@ export interface EntityInterface extends DataObjectInterface {
    * - $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.
+   * @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
@@ -232,22 +279,37 @@ export interface EntityInterface extends DataObjectInterface {
    * - $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.
+   * @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.
+   * 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): void;
+  $putData(
+    data: EntityData,
+    sdata?: SerializedEntityData,
+    source?: 'server',
+  ): void;
   /**
    * Remove one or more tags.
    *
@@ -257,12 +319,14 @@ export interface EntityInterface extends DataObjectInterface {
   /**
    * 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.
+   * 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.
    *
-   * @returns A Nymph Entity Reference array as an unsaved entity.
+   * @param existingOnly Whether to only turn existing entities into references.
+   * @returns A Nymph Entity Reference array.
    */
-  $toReference(): EntityReference | EntityInterface;
+  $toReference(existingOnly?: boolean): EntityReference | EntityInterface;
   /**
    * Set whether to use "skipAc" when accessing entity references.
    *
@@ -271,61 +335,9 @@ export interface EntityInterface extends DataObjectInterface {
   $useSkipAc(useSkipAc: boolean): void;
 }
 
-export type EntityConstructor = (new (...args: any[]) => EntityInterface) & {
-  /**
-   * The instance of Nymph to use for queries.
-   */
-  nymph: Nymph;
-  /**
-   * A unique name for this type of entity used to separate its data from other
-   * types of entities in the database.
-   */
-  ETYPE: string;
-  /**
-   * The lookup name for this entity.
-   *
-   * This is used for reference arrays (and sleeping references) and client
-   * requests.
-   */
-  class: string;
-  /**
-   * Properties that will not be searchable from the frontend. If the frontend
-   * includes any of these properties in any of their clauses, they will be
-   * filtered out before the search is executed.
-   */
-  searchRestrictedData: string[];
-  /**
-   * The names of static methods allowed to be called by the frontend with
-   * serverCallStatic.
-   */
-  clientEnabledStaticMethods: 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 database until it
-   * is actually used.
-   *
-   * @param reference The Nymph Entity Reference to use to wake.
-   * @returns The new instance.
-   */
-  factoryReference(reference: EntityReference): EntityInterface;
-  /**
-   * Alter the options for a query for this entity.
-   *
-   * @param options The current options.
-   * @returns The altered options.
-   */
-  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];
 };