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

package/README.md

@@ -1,8 +1,16 @@
 # Nymph
 
-Powerful object data storage and querying.
+Application Data and Access Framework for Node.js and the browser.
 
-The Nymph core provides the base level classes and utilities to query the database, save data to it, and define different data types.
+https://nymph.io/
+
+Nymph.js includes an object relational mapper with nested, atomic transactions, a powerful query language, a user and group manager with granular access controls, a REST server, a publish/subscribe server for real time collaboration, and a client for Node.js and the browser. It allows rapid prototyping and production ready speed and features.
+
+Nymph can use SQLite3, MySQL, or PostgreSQL as its database backend. You can use SQLite in development, and MySQL or Postgres in production. You can even use Nymph with SQLite in an Electron app.
+
+Nymph is the framework that powers the [Port87](https://port87.com) email service. It also powers [Nephele](https://forge.sciactive.com/sciactive/nephele)'s deduplication adapter. Nymph was started in 2009 as part of a framework called [Pines](https://sourceforge.net/projects/pines/). In 2012, it was spun off into its own project, and in 2021, it was migrated to Node.js. As part of Pines, it powered TECHsmart's entire ERP system for over a decade.
+
+The Nymph core package provides the base level classes and utilities to query the database, save data to it, and define different data types.
 
 ## Installation
 
@@ -12,7 +20,7 @@ npm install --save @nymphjs/nymph
 
 ## Drivers
 
-To use Nymph, you need a database driver. Nymph.js provides a [MySQL driver](../driver-mysql/README.md), a [PostgreSQL driver](../driver-postgresql/README.md), and a [SQLite3 driver](../driver-sqlite3/README.md). They all provide the exact same functionality.
+To use Nymph, you need a database driver. Nymph.js provides a [MySQL driver](../driver-mysql/README.md), a [PostgreSQL driver](../driver-postgresql/README.md), and a [SQLite3 driver](../driver-sqlite3/README.md). They all provide the exact same functionality (with the exception of alphanumerical sort order, which is dependent on database collation).
 
 ## Usage
 
@@ -46,7 +54,7 @@ async function run() {
 
   const otherPendingTodos = await nymph.getEntities(
     { class: Todo },
-    { type: '&', '!guid': myEntity.guid, equal: ['done', false] }
+    { type: '&', '!guid': myEntity.guid, equal: ['done', false] },
   );
 
   const total = otherPendingTodos.length;
@@ -54,7 +62,7 @@ async function run() {
   console.log(
     `Besides the one I just created, there ${
       single ? 'is' : 'are'
-    } ${total} pending todo${single ? '' : 's'} in the database.`
+    } ${total} pending todo${single ? '' : 's'} in the database.`,
   );
 }
 ```
@@ -72,23 +80,13 @@ export default class Todo extends Entity<TodoData> {
   static ETYPE = 'todo'; // This is used for the table name(s) in the DB.
   static class = 'Todo'; // This is used to map references to their class.
 
-  static async factory(guid?: string): Promise<Todo & TodoData> {
-    return (await super.factory(guid)) as Todo & TodoData;
-  }
-
-  static factorySync(guid?: string): Todo & TodoData {
-    return super.factorySync(guid) as Todo & TodoData;
-  }
-
-  constructor(guid?: string) {
-    super(guid);
+  constructor() {
+    super();
 
-    if (this.guid == null) {
-      // Within the methods of an entity, you will use `this.$data` to access
-      // its data. Outside, you don't need the $data part.
-      this.$data.text = '';
-      this.$data.done = false;
-    }
+    // Within the methods of an entity, you will use `this.$data` to access
+    // its data. Outside, you don't need the $data part.
+    this.$data.text = '';
+    this.$data.done = false;
   }
 
   async $getOtherTodos() {
@@ -97,7 +95,7 @@ export default class Todo extends Entity<TodoData> {
     // instance of Nymph, so it could be a transactional instance.
     const otherTodos = await this.$nymph.getEntities(
       { class: Todo },
-      { type: '!&', guid: this.guid }
+      { type: '!&', guid: this.guid },
     );
     return otherTodos;
   }
@@ -106,11 +104,23 @@ export default class Todo extends Entity<TodoData> {
 
 ## Options
 
-See the [config declaration file](src/conf/d.ts).
+See the [config declaration file](src/conf/index.ts).
+
+# Live Migrations
+
+Sometimes database changes can be live migrated. In these cases, running `needsMigration()` will tell you about them, and the docblock for that method will give you more information. You should always run this method after updating to a new version of Nymph to see what needs to be migrated, if anything.
+
+If a migration is needed, you should export the DB in the version you were using before, in case anything goes wrong during the migration.
+
+The next step is to use the `liveMigration(migrationType)` method with the correct migration type.
+
+If required (explained in the docblock), you might then need to run a specific import on all of your entities. This is very important, and you might not be able to use new features or upgrade further without performing this step.
+
+Note that you can always export the DB in the version you were previously using, completely clear the DB (drop all of the tables), then import the DB in the new version.
 
 # License
 
-Copyright 2021 SciActive Inc
+Copyright 2021-2026 SciActive Inc
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

package/dist/Entity.d.ts

@@ -1,57 +1,348 @@
-import type Nymph from './Nymph';
-import { ACProperties, EntityData, EntityInterface, EntityJson, EntityPatch, EntityReference, SerializedEntityData } from './Entity.types';
+import type Nymph from './Nymph.js';
+import type { Options } from './Nymph.types.js';
+import type { ACProperties, EntityConstructor, EntityData, EntityInterface, EntityJson, EntityObject, EntityPatch, EntityReference, SerializedEntityData } from './Entity.types.js';
+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;
+export type EntityObjectType<T extends EntityConstructor> = T extends new () => infer E ? EntityObject & EntityDataType<E> : never;
+/**
+ * Database abstraction object.
+ *
+ * Provides a way to access, manipulate, and store data in Nymph.
+ *
+ * The GUID is not set until the entity is saved. GUIDs must be unique forever,
+ * even after deletion. It's the job of the Nymph DB driver to make sure no two
+ * entities ever have the same GUID. This is generally done by using a large
+ * randomly generated ID.
+ *
+ * Each entity class has an etype that determines which table(s) in the database
+ * it belongs to. If two entity classes have the same etype, their data will be
+ * stored in the same table(s). This isn't a good idea, however, because
+ * references to an entity store a class name, not an etype.
+ *
+ * Tags are used to classify entities. Where an etype is used to separate data
+ * by tables, tags can be used to separate entities within a table. You can
+ * define specific tags to be protected, meaning they cannot be added/removed
+ * from the client. It can be useful to allow user defined tags, such as for
+ * blog posts.
+ *
+ * Simply calling $delete() will not unset the entity. It will still take up
+ * memory. Likewise, simply calling unset will not delete the entity from the
+ * DB.
+ *
+ * Some notes about $equals() and $is(), the replacements for "==":
+ *
+ * The == operator will likely not give you the result you want, since two
+ * instances of the same entity will fail that check, even though they represent
+ * the same data in the database.
+ *
+ * $equals() performs a more strict comparison of the entity to another. Use
+ * $equals() instead of the == operator when you want to check both the entities
+ * they represent, and the data inside them. In order to return true for
+ * $equals(), the entity and object must meet the following criteria:
+ *
+ * - They must be entities.
+ * - They must have equal GUIDs, or both must have no GUID.
+ * - Their data and tags must be equal.
+ *
+ * $is() performs a less strict comparison of the entity to another. Use $is()
+ * instead of the == operator when the entity's data may have been changed, but
+ * you only care if they represent the same entity. In order to return true, the
+ * entity and object must meet the following criteria:
+ *
+ * - They must be entities.
+ * - They must have equal GUIDs, or both must have no GUID.
+ * - If they have no GUIDs, their data and tags must be equal.
+ *
+ * Some notes about saving entities in other entity's properties:
+ *
+ * Entities use references in the DB to store an entity in their properties. The
+ * reference is stored as an array with the values:
+ *
+ * - 0 => The string 'nymph_entity_reference'
+ * - 1 => The referenced entity's GUID.
+ * - 2 => The referenced entity's class name.
+ *
+ * Since the referenced entity's class name (meaning the `class` static
+ * property, not the name of the class itself) is stored in the reference on the
+ * parent entity, if you change the class name in an update, you need to
+ * reassign all referenced entities of that class and resave.
+ *
+ * When an entity is loaded, it does not request its referenced entities from
+ * Nymph. Instead, it creates instances without data called sleeping references.
+ * When you first access an entity's data, if it is a sleeping reference, it
+ * will fill its data from the DB. You can call clearCache() to turn all the
+ * entities back into sleeping references.
+ */
 export default class Entity<T extends EntityData = EntityData> implements EntityInterface {
+    /**
+     * The instance of Nymph to use for queries.
+     */
     static nymph: Nymph;
+    /**
+     * A unique name for this type of entity used to separate its data from other
+     * types of entities in the database.
+     */
     static ETYPE: string;
+    /**
+     * The lookup name for this entity.
+     *
+     * This is used for reference arrays (and sleeping references) and client
+     * requests.
+     */
     static class: string;
     $nymph: Nymph;
     guid: string | null;
     cdate: number | null;
     mdate: number | null;
     tags: string[];
+    /**
+     * The data proxy handler.
+     */
     protected $dataHandler: Object;
+    /**
+     * The actual data store.
+     */
     protected $dataStore: T;
+    /**
+     * The actual sdata store.
+     */
     protected $sdata: SerializedEntityData;
+    /**
+     * The data proxy object.
+     */
     protected $data: T;
+    /**
+     * Whether this instance is a sleeping reference.
+     */
     protected $isASleepingReference: boolean;
+    /**
+     * The reference to use to wake.
+     */
     protected $sleepingReference: EntityReference | null;
+    /**
+     * A promise that resolved when the entity's data is wake.
+     */
+    protected $wakePromise: Promise<Entity<T>> | null;
+    /**
+     * Properties that will not be serialized into JSON with toJSON(). This
+     * can be considered a denylist, because these properties will not be set
+     * with incoming JSON.
+     *
+     * Clients CAN still determine what is in these properties, unless they are
+     * also listed in searchRestrictedData.
+     */
     protected $privateData: string[];
+    /**
+     * Whether this entity should publish changes to PubSub servers.
+     */
+    static 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.
+     */
+    static 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.
+     */
     static searchRestrictedData: string[];
+    /**
+     * Properties that can only be modified by server side code. They will still
+     * be visible on the frontend, unlike $privateData, but any changes to them
+     * that come from the frontend will be ignored.
+     *
+     * In addition to what's listed here, all of the access control properties
+     * will be included when Tilmeld is being used. These are:
+     *
+     * - acUser
+     * - acGroup
+     * - acOther
+     * - acRead
+     * - acWrite
+     * - acFull
+     * - user
+     * - group
+     *
+     * You should modify these through client enabled methods or the $save method
+     * instead, for safety.
+     */
     protected $protectedData: string[];
+    /**
+     * If this is defined, then it lists the only properties that will be
+     * accepted from incoming JSON. Any other properties will be ignored.
+     *
+     * If you use an allowlist, you don't need to use protectedData, since you
+     * can simply leave those entries out of allowlistData.
+     */
     protected $allowlistData?: string[];
+    /**
+     * Tags that can only be added/removed by server side code. They will still be
+     * visible on the frontend, but any changes to them that come from the
+     * frontend will be ignored.
+     */
     protected $protectedTags: string[];
+    /**
+     * If this is defined, then it lists the only tags that will be accepted from
+     * incoming JSON. Any other tags will be ignored.
+     */
     protected $allowlistTags?: string[];
+    /**
+     * The names of methods allowed to be called by the frontend with serverCall.
+     */
     protected $clientEnabledMethods: string[];
+    /**
+     * The names of static methods allowed to be called by the frontend with
+     * serverCallStatic.
+     */
     static clientEnabledStaticMethods: string[];
+    /**
+     * Whether to use "skipAc" when accessing entity references.
+     */
     private $skipAc;
+    /**
+     * The AC properties' values when the entity was loaded.
+     */
     private $originalAcValues;
-    constructor(guid?: string);
-    static factory(guid?: string): Promise<EntityInterface | Entity<EntityData>>;
-    static factorySync(guid?: string): Entity<EntityData>;
-    static factoryReference(reference: EntityReference): Entity<EntityData>;
-    toJSON(): EntityReference | EntityJson | null;
+    /**
+     * This is used to hold a generated GUID for a new entity.
+     */
+    private $guaranteedGUID;
+    /**
+     * 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.
+     */
+    constructor(..._rest: any[]);
+    private $existingProxy?;
+    protected $proxy(): this & T;
+    /**
+     * 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.
+     */
+    static factory<E extends Entity>(this: {
+        new (): E;
+    }, guid?: string): Promise<E & EntityDataType<E>>;
+    /**
+     * Create a new entity instance.
+     */
+    static factorySync<E extends Entity>(this: {
+        new (): E;
+    }): E & EntityDataType<E>;
+    /**
+     * 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.
+     */
+    static factoryReference<E extends Entity>(this: {
+        new (): E;
+    }, reference: EntityReference): 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.
+     */
+    static getUniques({ guid, cdate, mdate, tags, data, sdata, }: {
+        guid?: string;
+        cdate?: number;
+        mdate?: number;
+        tags: string[];
+        data: EntityData;
+        sdata?: SerializedEntityData;
+    }): Promise<string[]>;
+    /**
+     * Get a string for full text search for one of an entity's properties.
+     *
+     * The result will be tokenized and stored as the full text search index for
+     * use with "search" clauses.
+     *
+     * Return null to not include any tokens in the full text search storage.
+     *
+     * You shouldn't use any other entity data to transform the text, as it won't
+     * always be available. This function is meant for things like stripping HTML
+     * tags.
+     *
+     * @returns By default, returns the value if it is a string.
+     */
+    static getFTSText(_name: string, value: any): string | null;
+    toJSON(): EntityJson | EntityReference | null;
+    $setNymph(nymph: Nymph): void;
+    $getGuaranteedGUID(): string;
     $addTag(...tags: string[]): void;
     $arraySearch(array: any[], strict?: boolean): number;
     $clearCache(): void;
     $getClientEnabledMethods(): string[];
-    $delete(): Promise<boolean>;
+    $delete(): Promise<void>;
     $equals(object: any): boolean;
-    $getData(includeSData?: boolean): any;
+    $getData(includeSData?: boolean): T;
     $getSData(): SerializedEntityData;
+    $getUniques(): Promise<string[]>;
     $getOriginalAcValues(): ACProperties;
-    $getValidatable(): any;
+    $getCurrentAcValues(): ACProperties;
+    $getAcUid(): any;
+    $getAcGid(): any;
+    $getAcReadIds(): (string | null)[] | null;
+    $getAcWriteIds(): (string | null)[] | null;
+    $getAcFullIds(): (string | null)[] | null;
+    $getValidatable(): {
+        guid: string | null;
+        cdate: number | null;
+        mdate: number | null;
+        tags: string[];
+    } & T;
     $getTags(): string[];
     $hasTag(...tags: string[]): boolean;
     $inArray(array: any[], strict?: boolean): boolean;
     $is(object: any): boolean;
     $jsonAcceptData(input: EntityJson, allowConflict?: boolean): void;
     $jsonAcceptPatch(patch: EntityPatch, allowConflict?: boolean): void;
-    $putData(data: EntityData, sdata?: SerializedEntityData): void;
+    $putData(data: EntityData, sdata?: SerializedEntityData, _source?: 'server'): void;
+    /**
+     * Set up a sleeping reference.
+     * @param array $reference The reference to use to wake.
+     */
     protected $referenceSleep(reference: EntityReference): void;
-    protected $referenceWake(): boolean;
-    $refresh(): Promise<boolean | 0>;
+    /**
+     * Check if this is a sleeping reference and throw an error if so.
+     */
+    protected $check(): void;
+    /**
+     * Check if this is a sleeping reference.
+     */
+    $asleep(): boolean;
+    /**
+     * Wake from a sleeping reference.
+     */
+    $wake(): Promise<Entity<T>>;
+    $wakeAll(level?: number): Promise<Entity<T>>;
+    $refresh(): Promise<boolean>;
     $removeTag(...tags: string[]): void;
-    $save(): Promise<boolean>;
-    $toReference(): EntityReference | this;
+    $save(): Promise<void>;
+    $toReference(existingOnly?: boolean): EntityReference | (this & T);
     $useSkipAc(skipAc: boolean): void;
 }