@nymphjs/nymph 1.0.0-beta.11 → 1.0.0-beta.111

package/src/Entity.types.ts

@@ -1,15 +1,15 @@
-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];
@@ -22,6 +22,14 @@ 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;
   guid: string | null;
@@ -137,6 +145,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.
    *
@@ -162,9 +181,10 @@ 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 +198,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.
    *
@@ -239,15 +277,25 @@ export interface EntityInterface extends DataObjectInterface {
   /**
    * 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.
    *
    * `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 +305,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 +321,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];
 };