@nymphjs/nymph 1.0.0-beta.58 → 1.0.0-beta.59

package/src/Entity.ts

@@ -1,7 +1,8 @@
 import { difference, intersection, isEqual } from 'lodash';
 
 import type Nymph from './Nymph';
-import {
+import type { Options } from './Nymph.types';
+import type {
   ACProperties,
   EntityConstructor,
   EntityData,
@@ -23,6 +24,13 @@ import {
   uniqueStrings,
 } from './utils';
 
+export type EntityDataType<T> = T extends Entity<infer DataType>
+  ? DataType
+  : never;
+
+export type EntityInstanceType<T extends EntityConstructor> =
+  T extends new () => infer E ? E & EntityDataType<E> : never;
+
 /**
  * Database abstraction object.
  *
@@ -230,10 +238,18 @@ export default class Entity<T extends EntityData = EntityData>
    */
   private $originalAcValues: ACProperties | null = null;
 
+  /**
+   * Alter the options for a query for this entity.
+   *
+   * @param options The current options.
+   * @returns The altered options.
+   */
+  static alterOptions?<T extends Options>(options: T): T;
+
   /**
    * Initialize an entity.
    */
-  public constructor() {
+  public constructor(..._rest: any[]) {
     this.$nymph = (this.constructor as EntityConstructor).nymph;
     this.$dataHandler = {
       has: (data: EntityData, name: string) => {
@@ -432,30 +448,108 @@ export default class Entity<T extends EntityData = EntityData>
     }) as Entity<T>;
   }
 
-  public static async factory(guid?: string) {
+  /**
+   * Create or retrieve a new entity instance.
+   *
+   * Note that this will always return an entity, even if the GUID is not found.
+   *
+   * @param guid An optional GUID to retrieve.
+   */
+  public static async factory<E extends Entity>(
+    this: {
+      new (): E;
+    },
+    guid?: string,
+  ): Promise<E & EntityDataType<E>> {
     const entity = new this();
     if (guid != null) {
-      const entity = await this.nymph.getEntity(
+      const entity = await (
+        this as unknown as EntityConstructor
+      ).nymph.getEntity(
         {
-          class: this as any as EntityConstructor,
+          class: this as unknown as EntityConstructor,
         },
         { type: '&', guid },
       );
       if (entity != null) {
-        return entity;
+        return entity as E & EntityDataType<E>;
       }
     }
-    return entity;
+    return entity as E & EntityDataType<E>;
   }
 
-  public static factorySync() {
-    return new this();
+  /**
+   * Create a new entity instance.
+   */
+  public static factorySync<E extends Entity>(this: {
+    new (): E;
+  }): E & EntityDataType<E> {
+    return new this() as E & EntityDataType<E>;
   }
 
-  public static factoryReference(reference: EntityReference) {
+  /**
+   * Create a new sleeping reference instance.
+   *
+   * Sleeping references won't retrieve their data from the database until they
+   * are readied with `$wake()` or a parent's `$wakeAll()`.
+   *
+   * @param reference The Nymph Entity Reference to use to wake.
+   * @returns The new instance.
+   */
+  public static factoryReference<E extends Entity>(
+    this: {
+      new (): E;
+    },
+    reference: EntityReference,
+  ): E & EntityDataType<E> {
     const entity = new this();
     entity.$referenceSleep(reference);
-    return entity;
+    return entity as E & EntityDataType<E>;
+  }
+
+  /**
+   * 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 static method instantiates the entity,
+   * assigns all of the given data, then calls `$getUniques` and returns its
+   * output. This can have a performance impact if a lot of extra processing
+   * happens during any of these steps. You can override this method to
+   * calculate the unique strings faster, but you must return the same strings
+   * that would be returned by `$getUniques`.
+   *
+   * @returns Resolves to an array of entity's unique constraint strings.
+   */
+  public static async getUniques({
+    guid,
+    cdate,
+    mdate,
+    tags,
+    data,
+    sdata,
+  }: {
+    guid?: string;
+    cdate?: number;
+    mdate?: number;
+    tags: string[];
+    data: EntityData;
+    sdata?: SerializedEntityData;
+  }) {
+    const entity = new this();
+    if (guid != null) {
+      entity.guid = guid;
+    }
+    if (cdate != null) {
+      entity.cdate = cdate;
+    }
+    if (mdate != null) {
+      entity.mdate = mdate;
+    }
+    entity.tags = tags;
+    entity.$putData(data, sdata);
+    return await entity.$getUniques();
   }
 
   public toJSON() {
@@ -564,6 +658,10 @@ export default class Entity<T extends EntityData = EntityData>
     return this.$sdata;
   }
 
+  public async $getUniques(): Promise<string[]> {
+    return [];
+  }
+
   public $getOriginalAcValues(): ACProperties {
     this.$check();
 
@@ -719,8 +817,8 @@ export default class Entity<T extends EntityData = EntityData>
       protectedProps.push('acWrite');
       protectedProps.push('acFull');
       if (
-        ((this.constructor as typeof Entity).class !== 'User' &&
-          (this.constructor as typeof Entity).class !== 'Group') ||
+        ((this.constructor as EntityConstructor).class !== 'User' &&
+          (this.constructor as EntityConstructor).class !== 'Group') ||
         !(this.$nymph.tilmeld as any).currentUser ||
         (!(this.$nymph.tilmeld as any).currentUser.abilities?.includes(
           'tilmeld/admin',
@@ -789,8 +887,8 @@ export default class Entity<T extends EntityData = EntityData>
       protectedProps.push('acWrite');
       protectedProps.push('acFull');
       if (
-        ((this.constructor as typeof Entity).class !== 'User' &&
-          (this.constructor as typeof Entity).class !== 'Group') ||
+        ((this.constructor as EntityConstructor).class !== 'User' &&
+          (this.constructor as EntityConstructor).class !== 'Group') ||
         !(this.$nymph.tilmeld as any).currentUser ||
         (!(this.$nymph.tilmeld as any).currentUser.abilities?.includes(
           'tilmeld/admin',

package/src/Entity.types.ts

@@ -1,5 +1,5 @@
 import type Nymph from './Nymph';
-import type { Options } from './Nymph.types';
+import type Entity from './Entity';
 
 export type ACProperties = {
   user: string | null;
@@ -178,6 +178,18 @@ 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.
    *
@@ -277,73 +289,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;
-  /**
-   * Whether this entity should publish changes to PubSub servers.
-   */
-  pubSubEnabled: boolean;
-  /**
-   * Whether this entity should be accessible on the frontend through the REST
-   * server.
-   *
-   * If this is false, any request from the client that attempts to use this
-   * entity will fail.
-   */
-  restEnabled: boolean;
-  /**
-   * 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];
 };

package/src/Nymph.ts

@@ -1,6 +1,6 @@
 import { Config, ConfigDefaults as defaults } from './conf';
 import type { NymphDriver } from './driver';
-import Entity from './Entity';
+import Entity, { type EntityInstanceType } from './Entity';
 import type { EntityConstructor, EntityInterface } from './Entity.types';
 import { ClassNotAvailableError } from './errors';
 import type {
@@ -229,24 +229,43 @@ export default class Nymph {
    * Because this creates a subclass, don't use the class
    * returned from `getEntityClass` to check with `instanceof`.
    */
-  public addEntityClass<T extends EntityConstructor>(entityClass: T): T {
+  public addEntityClass<T extends EntityConstructor>(EntityClass: T): T {
+    if (EntityClass.class in this.entityClasses) {
+      this.config.debugLog(
+        'nymph',
+        `Adding duplicate class "${EntityClass.class}". This may be a mistake.`,
+      );
+    }
+
+    // Check that it doesn't have the same etype as any other class.
+    for (const ExistingClass of Object.values(this.entityClasses)) {
+      if (
+        EntityClass.ETYPE === ExistingClass.ETYPE &&
+        EntityClass.class !== EntityClass.class
+      ) {
+        this.config.debugLog(
+          'nymph',
+          `Adding class "${EntityClass.class}" with same etype as existing class "${ExistingClass.class}". This may be a mistake.`,
+        );
+      }
+    }
+
     const nymph = this;
-    class NymphEntity extends entityClass {
+    this.entityClasses[EntityClass.class] = class extends EntityClass {
       static nymph: Nymph = nymph;
 
       constructor(...args: any[]) {
         super(...args);
       }
-    }
-    this.entityClasses[entityClass.class] = NymphEntity;
-    return NymphEntity;
+    };
+    return this.entityClasses[EntityClass.class] as T;
   }
 
   /**
    * Get the class that uses the specified class name.
    */
-  public getEntityClass<T extends EntityConstructor>(className: T): T;
   public getEntityClass(className: string): EntityConstructor;
+  public getEntityClass<T extends EntityConstructor>(className: T): T;
   public getEntityClass<T extends EntityConstructor = EntityConstructor>(
     className: T | string,
   ): T | EntityConstructor {
@@ -263,6 +282,28 @@ export default class Nymph {
     throw new ClassNotAvailableError(`Tried to use missing class "${key}".`);
   }
 
+  /**
+   * Get the class that uses the specified etype.
+   *
+   * Note that it is fine, though unusual, for two classes to use the same
+   * etype. However, this can lead to very hard to diagnose bugs, so is
+   * generally discouraged.
+   */
+  public getEntityClassByEtype(etype: string): EntityConstructor {
+    for (const EntityClass of Object.values(this.entityClasses)) {
+      if (EntityClass.ETYPE === etype) {
+        return EntityClass;
+      }
+    }
+    this.config.debugError(
+      'nymph',
+      `Tried to use missing class by etype "${etype}".`,
+    );
+    throw new ClassNotAvailableError(
+      `Tried to use missing class by etype "${etype}".`,
+    );
+  }
+
   /**
    * Get a clone of this instance with cloned classes and event listeners.
    *
@@ -819,11 +860,11 @@ export default class Nymph {
   public async getEntities<T extends EntityConstructor = EntityConstructor>(
     options?: Options<T>,
     ...selectors: Selector[]
-  ): Promise<ReturnType<T['factorySync']>[]>;
+  ): Promise<EntityInstanceType<T>[]>;
   public async getEntities<T extends EntityConstructor = EntityConstructor>(
     options: Options<T> = {},
     ...selectors: Selector[]
-  ): Promise<ReturnType<T['factorySync']>[] | string[] | number> {
+  ): Promise<EntityInstanceType<T>[] | string[] | number> {
     try {
       for (let callback of this.beforeGetEntitiesCallbacks) {
         if (callback) {
@@ -861,7 +902,7 @@ export default class Nymph {
   public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T>,
     ...selectors: Selector[]
-  ): Promise<ReturnType<T['factorySync']> | null>;
+  ): Promise<EntityInstanceType<T> | null>;
   public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T> & { return: 'guid' },
     guid: string,
@@ -869,11 +910,11 @@ export default class Nymph {
   public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T>,
     guid: string,
-  ): Promise<ReturnType<T['factorySync']> | null>;
+  ): Promise<EntityInstanceType<T> | null>;
   public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T> = {},
     ...selectors: Selector[] | string[]
-  ): Promise<ReturnType<T['factorySync']> | string | number | null> {
+  ): Promise<EntityInstanceType<T> | string | number | null> {
     try {
       // Set up options and selectors.
       if (typeof selectors[0] === 'string') {

package/src/Nymph.types.ts

@@ -1,5 +1,5 @@
-import { EntityConstructor, EntityInterface } from './Entity.types';
-import Nymph from './Nymph';
+import type { EntityConstructor, EntityInterface } from './Entity.types';
+import type Nymph from './Nymph';
 
 export type NymphEventType =
   | 'connect'