@nymphjs/nymph 1.0.0-beta.91 → 1.0.0-beta.93

package/src/Entity.types.ts

@@ -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;

package/src/Nymph.ts

@@ -1,8 +1,14 @@
 import { Config, ConfigDefaults as defaults } from './conf/index.js';
 import type { NymphDriver } from './driver/index.js';
-import Entity, { type EntityInstanceType } from './Entity.js';
+import Entity, {
+  type EntityInstanceType,
+  type EntityObjectType,
+} from './Entity.js';
 import type { EntityConstructor, EntityInterface } from './Entity.types.js';
-import { ClassNotAvailableError } from './errors/index.js';
+import {
+  ClassNotAvailableError,
+  InvalidParametersError,
+} from './errors/index.js';
 import type {
   Selector,
   Options,
@@ -702,8 +708,8 @@ export default class Nymph {
    *   a top-level property. The method of sorting properties other than cdate
    *   and mdate is driver dependent. The only hard rule is that numbers should
    *   be sorted numerically (2 before 10). Defaults to "cdate".
-   * - return - What to return. "entity", "guid", or "count". Defaults to
-   *   "entity".
+   * - return - What to return. "entity", "object", "guid", or "count". Defaults
+   *   to "entity".
    * - source - Will be 'client' if the query came from a REST call.
    * - skipCache - If true, Nymph will skip the cache and retrieve the entity
    *   from the DB.
@@ -857,6 +863,10 @@ export default class Nymph {
     options: Options<T> & { return: 'guid' },
     ...selectors: Selector[]
   ): Promise<string[]>;
+  public async getEntities<T extends EntityConstructor = EntityConstructor>(
+    options: Options<T> & { return: 'object' },
+    ...selectors: Selector[]
+  ): Promise<EntityObjectType<T>[]>;
   public async getEntities<T extends EntityConstructor = EntityConstructor>(
     options?: Options<T>,
     ...selectors: Selector[]
@@ -864,7 +874,15 @@ export default class Nymph {
   public async getEntities<T extends EntityConstructor = EntityConstructor>(
     options: Options<T> = {},
     ...selectors: Selector[]
-  ): Promise<EntityInstanceType<T>[] | string[] | number> {
+  ): Promise<
+    EntityInstanceType<T>[] | EntityObjectType<T>[] | string[] | number
+  > {
+    if (options.source === 'client' && options.return === 'object') {
+      throw new InvalidParametersError(
+        'Object return type not allowed from client.',
+      );
+    }
+
     try {
       for (let callback of this.beforeGetEntitiesCallbacks) {
         if (callback) {
@@ -899,6 +917,10 @@ export default class Nymph {
     options: Options<T> & { return: 'guid' },
     ...selectors: Selector[]
   ): Promise<string | null>;
+  public async getEntity<T extends EntityConstructor = EntityConstructor>(
+    options: Options<T> & { return: 'object' },
+    ...selectors: Selector[]
+  ): Promise<EntityObjectType<T> | null>;
   public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T>,
     ...selectors: Selector[]
@@ -907,6 +929,10 @@ export default class Nymph {
     options: Options<T> & { return: 'guid' },
     guid: string,
   ): Promise<string | null>;
+  public async getEntity<T extends EntityConstructor = EntityConstructor>(
+    options: Options<T> & { return: 'object' },
+    guid: string,
+  ): Promise<EntityObjectType<T> | null>;
   public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T>,
     guid: string,
@@ -914,7 +940,15 @@ export default class Nymph {
   public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T> = {},
     ...selectors: Selector[] | string[]
-  ): Promise<EntityInstanceType<T> | string | number | null> {
+  ): Promise<
+    EntityInstanceType<T> | EntityObjectType<T> | string | number | null
+  > {
+    if (options.source === 'client' && options.return === 'object') {
+      throw new InvalidParametersError(
+        'Object return type not allowed from client.',
+      );
+    }
+
     try {
       // Set up options and selectors.
       if (typeof selectors[0] === 'string') {

package/src/Nymph.types.ts

@@ -208,10 +208,15 @@ export type Options<T extends EntityConstructor = EntityConstructor> = {
    */
   sort?: 'cdate' | 'mdate' | string;
   /**
-   * What to return, the entities with their data, just the GUIDs, or just a
-   * count.
+   * What to return, the entities with their data, just the entity data, just
+   * the GUIDs, or just a count.
+   *
+   * 'object' is only available on the server, as there are substantial security
+   * implications with using it. It returns the full entity data as a simple
+   * object. You should only use it for operations where instantiating the
+   * entities has an unacceptable performance cost.
    */
-  return?: 'entity' | 'guid' | 'count';
+  return?: 'entity' | 'object' | 'guid' | 'count';
   /**
    * Will be 'client' if the query came from a REST request or the PubSub
    * server. (Mainly used in Tilmeld for access control.)

package/src/driver/NymphDriver.ts

@@ -5,7 +5,7 @@ import strtotime from 'locutus/php/datetime/strtotime.js';
 
 import type Nymph from '../Nymph.js';
 import type { Selector, Options, FormattedSelector } from '../Nymph.types.js';
-import Entity, { type EntityInstanceType } from '../Entity.js';
+import type { EntityInstanceType, EntityObjectType } from '../Entity.js';
 import type {
   EntityConstructor,
   EntityData,
@@ -108,6 +108,10 @@ export default abstract class NymphDriver {
     options: Options<T> & { return: 'guid' },
     ...selectors: Selector[]
   ): Promise<string[]>;
+  abstract getEntities<T extends EntityConstructor = EntityConstructor>(
+    options: Options<T> & { return: 'object' },
+    ...selectors: Selector[]
+  ): Promise<EntityObjectType<T>[]>;
   abstract getEntities<T extends EntityConstructor = EntityConstructor>(
     options?: Options<T>,
     ...selectors: Selector[]
@@ -115,7 +119,9 @@ export default abstract class NymphDriver {
   abstract getEntities<T extends EntityConstructor = EntityConstructor>(
     options?: Options<T>,
     ...selectors: Selector[]
-  ): Promise<EntityInstanceType<T>[] | string[] | number>;
+  ): Promise<
+    EntityInstanceType<T>[] | EntityObjectType<T>[] | string[] | number
+  >;
   abstract getUID(name: string): Promise<number | null>;
   abstract importEntity(entity: {
     guid: string;
@@ -796,6 +802,30 @@ export default abstract class NymphDriver {
       svalue: string;
     },
   ): { result: any; process: () => string[] | Error };
+  protected getEntitiesRowLike<T extends EntityConstructor = EntityConstructor>(
+    options: Options<T> & { return: 'object' },
+    selectors: Selector[],
+    performQueryCallback: (data: {
+      options: Options<T>;
+      selectors: FormattedSelector[];
+      etype: string;
+    }) => {
+      result: any;
+    },
+    rowFetchCallback: () => any,
+    freeResultCallback: () => void,
+    getCountCallback: (row: any) => number,
+    getGUIDCallback: (row: any) => string,
+    getTagsAndDatesCallback: (row: any) => {
+      tags: string[];
+      cdate: number;
+      mdate: number;
+    },
+    getDataNameAndSValueCallback: (row: any) => {
+      name: string;
+      svalue: string;
+    },
+  ): { result: any; process: () => EntityObjectType<T>[] | Error };
   protected getEntitiesRowLike<T extends EntityConstructor = EntityConstructor>(
     options: Options<T>,
     selectors: Selector[],
@@ -848,7 +878,12 @@ export default abstract class NymphDriver {
     },
   ): {
     result: any;
-    process: () => EntityInstanceType<T>[] | string[] | number | Error;
+    process: () =>
+      | EntityInstanceType<T>[]
+      | EntityObjectType<T>[]
+      | string[]
+      | number
+      | Error;
   } {
     if (!this.isConnected()) {
       throw new UnableToConnectError('not connected to DB');
@@ -866,12 +901,19 @@ export default abstract class NymphDriver {
       }
     }
 
-    let entities: EntityInstanceType<T>[] | string[] = [];
+    let entities: EntityInstanceType<T>[] | EntityObjectType<T>[] | string[] =
+      [];
     let count = 0;
     const EntityClass =
       options.class ?? (this.nymph.getEntityClass('Entity') as T);
     const etype = EntityClass.ETYPE;
 
+    if (options.source === 'client' && options.return === 'object') {
+      throw new InvalidParametersError(
+        'Object return type not allowed from client.',
+      );
+    }
+
     // Check if the requested entity is cached.
     if (
       this.nymph.config.cache &&
@@ -888,33 +930,75 @@ export default abstract class NymphDriver {
         (Object.keys(selectors[0]).length === 2 ||
           (Object.keys(selectors[0]).length === 3 && 'tag' in selectors[0]))
       ) {
-        const entity = this.pullCache<EntityInstanceType<T>>(
-          selectors[0]['guid'],
-          EntityClass.class,
-          !!options.skipAc,
-        );
+        const cacheEntity = this.pullCache(selectors[0]['guid']);
+
         if (
-          entity != null &&
-          entity.guid != null &&
+          cacheEntity != null &&
+          cacheEntity.guid != null &&
           (!('tag' in selectors[0]) ||
-            entity.hasTag(
-              ...(Array.isArray(selectors[0].tag)
+            !(
+              Array.isArray(selectors[0].tag)
                 ? selectors[0].tag
-                : [selectors[0].tag]),
-            ))
+                : [selectors[0].tag]
+            ).find((tag) => tag == null || !cacheEntity.tags.includes(tag)))
         ) {
-          const guid = entity.guid;
-          return {
-            result: Promise.resolve(null),
-            process: () =>
-              options.return === 'count'
-                ? guid
-                  ? 1
-                  : 0
-                : options.return === 'guid'
-                  ? [guid]
-                  : [entity],
-          };
+          // Return the value from the cache.
+          const { guid, cdate, mdate, tags, data, sdata } = cacheEntity;
+
+          if (options.return === 'count') {
+            return {
+              result: Promise.resolve(null),
+              process: () => 1,
+            };
+          } else if (options.return === 'guid') {
+            return {
+              result: Promise.resolve(null),
+              process: () => [guid],
+            };
+          } else if (options.return === 'object') {
+            return {
+              result: Promise.resolve(null),
+              process: () => [
+                {
+                  guid,
+                  cdate,
+                  mdate,
+                  tags,
+                  ...data,
+                  ...Object.fromEntries(
+                    Object.entries(sdata).map(([name, value]) => [
+                      name,
+                      JSON.parse(value),
+                    ]),
+                  ),
+                } as EntityObjectType<T>,
+              ],
+            };
+          } else {
+            const entity = this.nymph
+              .getEntityClass(EntityClass.class)
+              .factorySync() as EntityInstanceType<T>;
+            if (entity) {
+              entity.$nymph = this.nymph;
+              if (options.skipAc != null) {
+                entity.$useSkipAc(!!options.skipAc);
+              }
+              entity.guid = guid;
+              entity.cdate = cdate;
+              entity.mdate = mdate;
+              entity.tags = tags;
+              entity.$putData(data, sdata, 'server');
+              return {
+                result: Promise.resolve(null),
+                process: () => [entity],
+              };
+            }
+
+            return {
+              result: Promise.resolve(null),
+              process: () => [],
+            };
+          }
         }
       }
     }
@@ -971,26 +1055,43 @@ export default abstract class NymphDriver {
                 // Make sure that $row is incremented :)
                 row = rowFetchCallback();
               }
-              const entity = EntityClass.factorySync() as EntityInstanceType<T>;
-              entity.$nymph = this.nymph;
-              if (options.skipAc != null) {
-                entity.$useSkipAc(!!options.skipAc);
-              }
-              entity.guid = guid;
-              entity.cdate = cdate;
-              entity.mdate = mdate;
-              entity.tags = tags;
-              this.putDataCounter++;
-              if (this.putDataCounter == 100) {
-                throw new Error('Infinite loop detected in Entity loading.');
+
+              if (options.return === 'object') {
+                (entities as EntityObjectType<T>[]).push({
+                  guid,
+                  cdate,
+                  mdate,
+                  tags,
+                  ...data,
+                  ...Object.fromEntries(
+                    Object.entries(sdata).map(([name, value]) => [
+                      name,
+                      JSON.parse(value),
+                    ]),
+                  ),
+                } as EntityObjectType<T>);
+              } else {
+                const entity =
+                  EntityClass.factorySync() as EntityInstanceType<T>;
+                entity.$nymph = this.nymph;
+                if (options.skipAc != null) {
+                  entity.$useSkipAc(!!options.skipAc);
+                }
+                entity.guid = guid;
+                entity.cdate = cdate;
+                entity.mdate = mdate;
+                entity.tags = tags;
+                this.putDataCounter++;
+                if (this.putDataCounter == 100) {
+                  throw new Error('Infinite loop detected in Entity loading.');
+                }
+                entity.$putData(data, sdata, 'server');
+                this.putDataCounter--;
+                entities.push(entity);
               }
-              entity.$putData(data, sdata, 'server');
-              this.putDataCounter--;
               if (this.nymph.config.cache) {
                 this.pushCache(guid, cdate, mdate, tags, data, sdata);
               }
-              // @ts-ignore: ts doesn't know the return type here.
-              entities.push(entity);
             }
           }
 
@@ -1128,36 +1229,30 @@ export default abstract class NymphDriver {
    * Pull an entity from the cache.
    *
    * @param guid The entity's GUID.
-   * @param className The entity's class.
-   * @param useSkipAc Whether to tell the entity to use skip_ac.
-   * @returns The entity or null if it's not cached.
+   * @returns The entity's data or null if it's not cached.
    */
-  protected pullCache<T extends Entity>(
-    guid: string,
-    className: string,
-    useSkipAc = false,
-  ): T | null {
+  protected pullCache(guid: string): {
+    guid: string;
+    cdate: number;
+    mdate: number;
+    tags: string[];
+    data: EntityData;
+    sdata: SerializedEntityData;
+  } | null {
     // Increment the entity access count.
     if (!(guid in this.entityCount)) {
       this.entityCount[guid] = 0;
     }
     this.entityCount[guid]++;
     if (guid in this.entityCache) {
-      const entity = this.nymph.getEntityClass(className).factorySync() as T;
-      if (entity) {
-        entity.$nymph = this.nymph;
-        entity.$useSkipAc(!!useSkipAc);
-        entity.guid = guid;
-        entity.cdate = this.entityCache[guid]['cdate'];
-        entity.mdate = this.entityCache[guid]['mdate'];
-        entity.tags = this.entityCache[guid]['tags'];
-        entity.$putData(
-          this.entityCache[guid]['data'],
-          this.entityCache[guid]['sdata'],
-          'server',
-        );
-        return entity;
-      }
+      return {
+        guid,
+        cdate: this.entityCache[guid]['cdate'],
+        mdate: this.entityCache[guid]['mdate'],
+        tags: this.entityCache[guid]['tags'],
+        data: this.entityCache[guid]['data'],
+        sdata: this.entityCache[guid]['sdata'],
+      };
     }
     return null;
   }
@@ -1194,11 +1289,11 @@ export default abstract class NymphDriver {
     }
     // Cache the entity.
     this.entityCache[guid] = {
-      cdate: cdate,
-      mdate: mdate,
-      tags: tags,
-      data: data,
-      sdata: sdata,
+      cdate,
+      mdate,
+      tags,
+      data,
+      sdata,
     };
     while (
       this.nymph.config.cacheLimit &&

package/src/driver/testArtifacts.ts

@@ -1530,6 +1530,61 @@ export function EntitiesTest(
     expect(resultGuid.indexOf(testEntity.guid ?? '')).toBeGreaterThan(-1);
   });
 
+  it('object return', async () => {
+    await createTestEntities();
+
+    // Testing object return using logic operations...
+    const resultObjects = await nymph.getEntities(
+      { class: TestModel, return: 'object' },
+      {
+        type: '&',
+        '!ref': [
+          ['refArray', guid()],
+          ['refArray', guid()],
+        ],
+        '!lte': ['number', 29.99],
+      },
+      {
+        type: '|',
+        '!lte': [
+          ['number', 29.99],
+          ['number', 30],
+        ],
+      },
+      {
+        type: '!&',
+        '!equal': ['string', 'test'],
+        '!contain': [
+          ['array', 'full'],
+          ['array', 'of'],
+          ['array', 'values'],
+          ['array', 500],
+          ['array', { test: true }],
+          ['array', { nullbyte: '\\\x00\u0000  \x00' }],
+        ],
+      },
+      {
+        type: '!|',
+        '!equal': ['string', 'test'],
+        contain: [
+          ['array', 'full'],
+          ['array', 'of'],
+          ['array', 'values'],
+          ['array', 500],
+        ],
+      },
+    );
+
+    const resultObject = resultObjects.find(
+      (entity) => entity.guid === testEntity.guid,
+    );
+
+    expect(resultObject).toBeInstanceOf(Object);
+    expect(resultObject).not.toBeInstanceOf(TestModel);
+    expect(Array.isArray(resultObject?.tags)).toBeTruthy();
+    expect(resultObject?.string).toEqual('test');
+  });
+
   it('deep selector', async () => {
     await createTestEntities();
 

package/src/testMocks.ts

@@ -1,7 +1,7 @@
 import { guid } from '@nymphjs/guid';
 
 import type Nymph from './Nymph.js';
-import type { EntityInstanceType } from './Entity.js';
+import type { EntityInstanceType, EntityObjectType } from './Entity.js';
 import type {
   EntityConstructor,
   EntityInterface,
@@ -24,6 +24,10 @@ export class MockNymphDriver {
     options: Options<T> & { return: 'guid' },
     ...selectors: Selector[]
   ): Promise<string | null>;
+  public async getEntity<T extends EntityConstructor = EntityConstructor>(
+    options: Options<T> & { return: 'object' },
+    ...selectors: Selector[]
+  ): Promise<EntityObjectType<T> | null>;
   public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T>,
     ...selectors: Selector[]
@@ -32,6 +36,10 @@ export class MockNymphDriver {
     options: Options<T> & { return: 'guid' },
     guid: string,
   ): Promise<string | null>;
+  public async getEntity<T extends EntityConstructor = EntityConstructor>(
+    options: Options<T> & { return: 'object' },
+    guid: string,
+  ): Promise<EntityObjectType<T> | null>;
   public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T>,
     guid: string,
@@ -39,7 +47,7 @@ export class MockNymphDriver {
   public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T> = {},
     ...selectors: Selector[] | string[]
-  ): Promise<EntityInstanceType<T> | string | null> {
+  ): Promise<EntityInstanceType<T> | EntityObjectType<T> | string | null> {
     const guid =
       typeof selectors[0] === 'string' ? selectors[0] : selectors[0].guid;
     if (!options || !guid || typeof guid !== 'string' || !(guid in entities)) {
@@ -117,6 +125,10 @@ export class MockNymph {
     options: Options<T> & { return: 'guid' },
     ...selectors: Selector[]
   ): Promise<string | null>;
+  public async getEntity<T extends EntityConstructor = EntityConstructor>(
+    options: Options<T> & { return: 'object' },
+    ...selectors: Selector[]
+  ): Promise<EntityObjectType<T> | null>;
   public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T>,
     ...selectors: Selector[]
@@ -125,6 +137,10 @@ export class MockNymph {
     options: Options<T> & { return: 'guid' },
     guid: string,
   ): Promise<string | null>;
+  public async getEntity<T extends EntityConstructor = EntityConstructor>(
+    options: Options<T> & { return: 'object' },
+    guid: string,
+  ): Promise<EntityObjectType<T> | null>;
   public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T>,
     guid: string,
@@ -132,7 +148,7 @@ export class MockNymph {
   public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T> = {},
     ...selectors: Selector[] | string[]
-  ): Promise<EntityInstanceType<T> | string | null> {
+  ): Promise<EntityInstanceType<T> | EntityObjectType<T> | string | null> {
     // @ts-ignore: The selector type is correct here.
     return await this.driver.getEntity(options, ...selectors);
   }