@nymphjs/nymph 1.0.0-beta.121 → 1.0.0-beta.122

package/src/driver/testArtifacts.ts

@@ -5,7 +5,10 @@ import { strtotime } from 'locutus/php/datetime/index';
 import { guid } from '@nymphjs/guid';
 
 import type Nymph from '../Nymph.js';
-import { EntityUniqueConstraintError } from '../errors/index.js';
+import {
+  EntityUniqueConstraintError,
+  EntityInvalidDataError,
+} from '../errors/index.js';
 import {
   TestBModel as TestBModelClass,
   TestModel as TestModelClass,
@@ -56,22 +59,22 @@ export function EntitiesTest(
       testEntity.number = 30;
       testEntity.numberString = '30';
       testEntity.timestamp = Date.now();
-      expect(await testEntity.$save()).toEqual(true);
+      await testEntity.$save();
       expect(testEntity.guid).not.toBeNull();
       testGuid = testEntity.guid as string;
 
       const entityReferenceTest: TestModelClass & TestModelData =
         new TestModel();
-      entityReferenceTest.string = 'wrong';
+      entityReferenceTest.string = 'ref string';
       entityReferenceTest.timestamp = (strtotime('-2 days') || 0) * 1000;
-      expect(await entityReferenceTest.$save()).toEqual(true);
+      await entityReferenceTest.$save();
       refGuid = entityReferenceTest.guid as string;
       testEntity.reference = entityReferenceTest;
       testEntity.refArray = [entityReferenceTest];
-      expect(await testEntity.$save()).toEqual(true);
+      await testEntity.$save();
 
       entityReferenceTest.test = 'good';
-      expect(await entityReferenceTest.$save()).toEqual(true);
+      await entityReferenceTest.$save();
 
       // Test asynchronous getEntity.
       testEntity = (await nymph.getEntity(
@@ -94,7 +97,7 @@ export function EntitiesTest(
           testEntity.number = 100 - i;
           testEntity.$removeTag('test');
           testEntity.$addTag('multiTest');
-          expect(await testEntity.$save()).toEqual(true);
+          await testEntity.$save();
           // Pause for a few milliseconds so the cdate and mdate can be sorted.
           await new Promise((res) => setTimeout(() => res(1), 5));
         }
@@ -105,7 +108,7 @@ export function EntitiesTest(
       let amodels = await nymph.getEntities({ class: TestModel });
       expect(Array.isArray(amodels)).toEqual(true);
       for (const cur of amodels) {
-        expect(await cur.$delete()).toEqual(true);
+        await cur.$delete();
       }
 
       amodels = await nymph.getEntities({ class: TestModel });
@@ -114,7 +117,7 @@ export function EntitiesTest(
       let bmodels = await nymph.getEntities({ class: TestBModel });
       expect(Array.isArray(bmodels)).toEqual(true);
       for (const cur of bmodels) {
-        expect(await cur.$delete()).toEqual(true);
+        await cur.$delete();
       }
 
       bmodels = await nymph.getEntities({ class: TestBModel });
@@ -128,7 +131,13 @@ export function EntitiesTest(
     it("doesn't create empty entity", async () => {
       const testEntity = await TestEmptyModel.factory();
 
-      expect(await testEntity.$save()).toBeFalsy();
+      try {
+        await testEntity.$save();
+
+        throw new Error('Should have thrown.');
+      } catch (e: any) {
+        expect(e).toBeInstanceOf(EntityInvalidDataError);
+      }
       expect(testEntity.guid).toBeNull();
     });
 
@@ -180,7 +189,7 @@ export function EntitiesTest(
       // Get the guaranteed GUID.
       const testGuid = testEntity.$getGuaranteedGUID();
 
-      expect(await testEntity.$save()).toEqual(true);
+      await testEntity.$save();
       expect(testEntity.guid).not.toBeNull();
       expect(testEntity.guid).toEqual(testGuid);
 
@@ -189,7 +198,7 @@ export function EntitiesTest(
       expect(testEntity.$is(resultEntity)).toEqual(true);
 
       // Delete the entity.
-      expect(await testEntity.$delete()).toEqual(true);
+      await testEntity.$delete();
     });
 
     it('create, list, and delete indexes', async () => {
@@ -324,7 +333,7 @@ export function EntitiesTest(
 
       // Change a value in the test entity.
       testEntity.string = 'bad value';
-      expect(await testEntity.$save()).toEqual(true);
+      await testEntity.$save();
 
       // Rollback the transaction.
       await transaction.rollback('test');
@@ -344,7 +353,7 @@ export function EntitiesTest(
       expect(await transaction.inTransaction()).toEqual(true);
 
       // Delete the entity.
-      expect(await testEntity.$delete()).toEqual(true);
+      await testEntity.$delete();
       const resultEntity = await transaction.getEntity(
         { class: TestModel },
         testGuid,
@@ -374,7 +383,7 @@ export function EntitiesTest(
 
       // Make a change.
       testEntity.string = 'fish';
-      expect(await testEntity.$save()).toEqual(true);
+      await testEntity.$save();
 
       // Commit the transaction.
       await transaction.commit('test.1');
@@ -389,11 +398,103 @@ export function EntitiesTest(
 
       // Finally, change it back.
       testEntity.string = 'test';
-      expect(await testEntity.$save()).toEqual(true);
+      await testEntity.$save();
 
       // TODO: nested transactions
     });
 
+    it('transactional decorator', async () => {
+      await createTestEntities();
+
+      if (testEntity.reference == null) {
+        throw new Error('Reference is null.');
+      }
+      await testEntity.reference.$wake();
+
+      expect(testEntity.string).toEqual('test');
+      expect(testEntity.reference.string).toEqual('ref string');
+
+      try {
+        await testEntity.$testTransactionalDecorator(true);
+
+        throw Error('Should have thrown an error.');
+      } catch (e: any) {
+        expect(e.message).toEqual('An error.');
+      }
+
+      if (!(await testEntity.$refresh())) {
+        throw new Error("Entity couldn't be refreshed.");
+      }
+      await testEntity.reference.$wake();
+
+      expect(testEntity.string).toEqual('test');
+      expect(testEntity.reference.string).toEqual('ref string');
+
+      expect(await testEntity.$testTransactionalDecorator(false)).toEqual(
+        'Success.',
+      );
+
+      if (!(await testEntity.$refresh())) {
+        throw new Error("Entity couldn't be refreshed.");
+      }
+      await testEntity.reference.$wake();
+
+      expect(testEntity.string).toEqual('this has been changed');
+      expect(testEntity.reference.string).toEqual('this has been changed too');
+
+      // Reset back to original values.
+      testEntity.reference.string = 'ref string';
+      await testEntity.reference.$save();
+      testEntity.string = 'test';
+      await testEntity.$save();
+    });
+
+    it('transaction helper', async () => {
+      await createTestEntities();
+
+      if (testEntity.reference == null) {
+        throw new Error('Reference is null.');
+      }
+      await testEntity.reference.$wake();
+
+      expect(testEntity.string).toEqual('test');
+      expect(testEntity.reference.string).toEqual('ref string');
+
+      try {
+        await testEntity.$testTransactionHelper(true);
+
+        throw Error('Should have thrown an error.');
+      } catch (e: any) {
+        expect(e.message).toEqual('An error.');
+      }
+
+      if (!(await testEntity.$refresh())) {
+        throw new Error("Entity couldn't be refreshed.");
+      }
+      await testEntity.reference.$wake();
+
+      expect(testEntity.string).toEqual('test');
+      expect(testEntity.reference.string).toEqual('ref string');
+
+      expect(await testEntity.$testTransactionHelper(false)).toEqual(
+        'Success.',
+      );
+
+      if (!(await testEntity.$refresh())) {
+        throw new Error("Entity couldn't be refreshed.");
+      }
+      await testEntity.reference.$wake();
+
+      expect(testEntity.string).toEqual('this has been changed');
+      expect(testEntity.reference.string).toEqual('this has been changed too');
+
+      // Reset back to original values.
+      testEntity.reference.string = 'ref string';
+      await testEntity.reference.$save();
+      testEntity.string = 'test';
+      await testEntity.$save();
+    });
+
     it('options', async () => {
       await createTestEntities();
 
@@ -674,7 +775,7 @@ export function EntitiesTest(
       // Retrieving entity by !equal...
       const resultEntity = await nymph.getEntities(
         { class: TestModel },
-        { type: '&', tag: 'test', '!equal': ['string', 'wrong'] },
+        { type: '&', tag: 'test', '!equal': ['string', 'ref string'] },
       );
       expect(testEntity.$inArray(resultEntity)).toEqual(true);
       expect(referenceEntity.$inArray(resultEntity)).toEqual(false);
@@ -700,7 +801,7 @@ export function EntitiesTest(
       // Retrieving entity by !like...
       const resultEntity = await nymph.getEntities(
         { class: TestModel },
-        { type: '&', tag: 'test', '!like': ['string', 'wr_n%'] },
+        { type: '&', tag: 'test', '!like': ['string', 'r_f%'] },
       );
       expect(testEntity.$inArray(resultEntity)).toEqual(true);
       expect(referenceEntity.$inArray(resultEntity)).toEqual(false);
@@ -726,7 +827,7 @@ export function EntitiesTest(
       // Retrieving entity by !ilike...
       const resultEntity = await nymph.getEntities(
         { class: TestModel },
-        { type: '&', tag: 'test', '!ilike': ['string', 'wr_n%'] },
+        { type: '&', tag: 'test', '!ilike': ['string', 'r_f%'] },
       );
       expect(testEntity.$inArray(resultEntity)).toEqual(true);
       expect(referenceEntity.$inArray(resultEntity)).toEqual(false);
@@ -2130,14 +2231,19 @@ export function EntitiesTest(
       await createMultipleTestEntities();
 
       for (const sort of ['cdate', 'mdate'] as ('cdate' | 'mdate')[]) {
+        // These ones might have the same dates (saved at exactly the same time)
+        // so we use >= and <= instead of > and <.
         // Retrieving entities sorted...
         let resultEntities = await nymph.getEntities({
           class: TestModel,
           sort,
         });
         expect(resultEntities.length).toBeGreaterThan(100);
+        expect(resultEntities[resultEntities.length - 1][sort]).toBeGreaterThan(
+          resultEntities[0][sort] ?? 0,
+        );
         for (let i = 0; i < resultEntities.length - 1; i++) {
-          expect(resultEntities[i + 1][sort]).toBeGreaterThan(
+          expect(resultEntities[i + 1][sort]).toBeGreaterThanOrEqual(
             resultEntities[i][sort] ?? 0,
           );
         }
@@ -2160,13 +2266,17 @@ export function EntitiesTest(
           reverse: true,
         });
         expect(resultEntities.length).toBeGreaterThan(100);
+        expect(resultEntities[resultEntities.length - 1][sort]).toBeLessThan(
+          resultEntities[0][sort] ?? 0,
+        );
         for (let i = 0; i < resultEntities.length - 1; i++) {
-          expect(resultEntities[i + 1][sort]).toBeLessThan(
+          expect(resultEntities[i + 1][sort]).toBeLessThanOrEqual(
             resultEntities[i][sort] ?? 0,
           );
         }
 
         // And again with other selectors.
+        // These ones should have different dates every time.
         // Retrieving entities sorted...
         resultEntities = await nymph.getEntities(
           { class: TestModel, sort },
@@ -2269,7 +2379,7 @@ export function EntitiesTest(
 
       // Deleting referenced entities...
       await testEntity.reference?.$wake();
-      expect(await testEntity.reference?.$delete()).toEqual(true);
+      await testEntity.reference?.$delete();
       await Promise.all(testEntity.refArray?.map((e) => e.$wake()) || []);
       expect(testEntity.reference?.guid).toBeNull();
     });
@@ -2278,7 +2388,7 @@ export function EntitiesTest(
       await createTestEntities();
 
       // Deleting entity...
-      expect(await testEntity.$delete()).toEqual(true);
+      await testEntity.$delete();
       expect(testEntity.guid).toBeNull();
 
       const entity = await nymph.getEntity(
@@ -2296,7 +2406,7 @@ export function EntitiesTest(
       uniqueEntityA.uniques = ['test a'];
 
       // Saving entity...
-      expect(await uniqueEntityA.$save()).toEqual(true);
+      await uniqueEntityA.$save();
       expect(uniqueEntityA.guid).not.toBeNull();
 
       // Creating entity...
@@ -2305,13 +2415,13 @@ export function EntitiesTest(
       uniqueEntityB.uniques = ['test b'];
 
       // Saving entity...
-      expect(await uniqueEntityB.$save()).toEqual(true);
+      await uniqueEntityB.$save();
       expect(uniqueEntityB.guid).not.toBeNull();
 
       expect(uniqueEntityA.guid).not.toEqual(uniqueEntityB.guid);
 
-      expect(await uniqueEntityA.$delete()).toEqual(true);
-      expect(await uniqueEntityB.$delete()).toEqual(true);
+      await uniqueEntityA.$delete();
+      await uniqueEntityB.$delete();
     });
 
     it('throws on duplicate unique strings', async () => {
@@ -2321,7 +2431,7 @@ export function EntitiesTest(
       uniqueEntityA.uniques = ['test a'];
 
       // Saving entity...
-      expect(await uniqueEntityA.$save()).toEqual(true);
+      await uniqueEntityA.$save();
       expect(uniqueEntityA.guid).not.toBeNull();
 
       // Creating entity...
@@ -2339,7 +2449,7 @@ export function EntitiesTest(
       }
       expect(uniqueEntityB.guid).toBeNull();
 
-      expect(await uniqueEntityA.$delete()).toEqual(true);
+      await uniqueEntityA.$delete();
     });
 
     it('allows duplicate unique string if first transaction is rolled back', async () => {
@@ -2351,7 +2461,7 @@ export function EntitiesTest(
       uniqueEntityA.uniques = ['test a'];
 
       // Saving entity...
-      expect(await uniqueEntityA.$save()).toEqual(true);
+      await uniqueEntityA.$save();
       expect(uniqueEntityA.guid).not.toBeNull();
 
       // Rolling back transaction...
@@ -2365,7 +2475,7 @@ export function EntitiesTest(
       uniqueEntityB.uniques = ['test a'];
 
       // Saving entity...
-      expect(await uniqueEntityB.$save()).toEqual(true);
+      await uniqueEntityB.$save();
       expect(uniqueEntityB.guid).not.toBeNull();
 
       expect(uniqueEntityA.guid).not.toEqual(uniqueEntityB.guid);
@@ -2385,7 +2495,7 @@ export function EntitiesTest(
       expect(uniqueEntityBCheck).not.toBeNull();
 
       if (uniqueEntityBCheck != null) {
-        expect(await uniqueEntityBCheck.$delete()).toEqual(true);
+        await uniqueEntityBCheck.$delete();
       }
     });
   });
@@ -2448,7 +2558,7 @@ export function ExportImportTest(
       let all = await nymph.getEntities({ class: TestModel });
       expect(Array.isArray(all)).toEqual(true);
       for (const cur of all) {
-        expect(await cur.$delete()).toEqual(true);
+        await cur.$delete();
       }
 
       all = await nymph.getEntities({ class: TestModel });
@@ -2457,7 +2567,7 @@ export function ExportImportTest(
       all = await nymph.getEntities({ class: TestBModel });
       expect(Array.isArray(all)).toEqual(true);
       for (const cur of all) {
-        expect(await cur.$delete()).toEqual(true);
+        await cur.$delete();
       }
 
       all = await nymph.getEntities({ class: TestBModel });
@@ -2547,11 +2657,11 @@ export function ExportImportTest(
         entityReferenceTest.string = 'another';
         entityReferenceTest.index = i + 'b';
 
-        expect(await entityReferenceTest.$save()).toEqual(true);
+        await entityReferenceTest.$save();
         testEntity.reference = entityReferenceTest;
         testEntity.refArray = [entityReferenceTest];
 
-        expect(await testEntity.$save()).toEqual(true);
+        await testEntity.$save();
       }
 
       await checkEntityDataAndCount();

package/src/errors/MethodFailedError.ts

@@ -0,0 +1,6 @@
+export class MethodFailedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'MethodFailedError';
+  }
+}

package/src/errors/index.ts

@@ -14,6 +14,8 @@ export * from './InvalidParametersError.js';
 
 export * from './InvalidStateError.js';
 
+export * from './MethodFailedError.js';
+
 export * from './NotConfiguredError.js';
 
 export * from './QueryFailedError.js';

package/src/helpers/index.ts

@@ -0,0 +1 @@
+export * from './transaction.js';

package/src/helpers/transaction.ts

@@ -0,0 +1,65 @@
+import Nymph from '../Nymph.js';
+
+/**
+ * Run a function inside of a transaction.
+ *
+ * @param nymph The instance of Nymph to start the transaction on.
+ * @param name The name of the transaction.
+ * @param fn The function that runs inside the transaction. It is passed the
+ *           transactional instance of Nymph. If it resolves, the transaction is
+ *           committed, and if it throws, the transaction is rolled back.
+ * @param finallyFn An optional function to run after the transaction is
+ *                  committed or rolled back. It is passed the original instance
+ *                  of Nymph. It SHOULD NOT throw.
+ * @returns The return value of the function.
+ */
+export async function transaction<T>(
+  nymph: Nymph,
+  name: string,
+  fn: (nymph: Nymph) => Promise<T>,
+  finallyFn?: (nymph: Nymph) => Promise<void>,
+): Promise<T> {
+  nymph.config.debugInfo('nymph:transaction', `Starting transaction ${name}`);
+  const tnymph = await nymph.startTransaction(name);
+  try {
+    const result = await fn(tnymph);
+
+    nymph.config.debugInfo(
+      'nymph:transaction',
+      `Committing transaction ${name}`,
+    );
+    if (!(await tnymph.commit(name))) {
+      throw new Error('Transaction could not be committed.');
+    }
+
+    if (finallyFn) {
+      await finallyFn(nymph);
+    }
+
+    return result;
+  } catch (e: any) {
+    try {
+      nymph.config.debugInfo(
+        'nymph:transaction',
+        `Rolling back transaction ${name}, reason: ${e.message}`,
+      );
+      await tnymph.rollback(name);
+    } catch (e: any) {
+      nymph.config.debugError(
+        'nymph:transaction',
+        `Rollback of transaction ${name} failed, reason: ${e.message}`,
+      );
+    }
+    if (finallyFn) {
+      try {
+        await finallyFn(nymph);
+      } catch (e: any) {
+        nymph.config.debugError(
+          'nymph:transaction',
+          `Finally function of transaction ${name} threw error: ${e.message}, this is a mistake and should be fixed, finally functions should never throw`,
+        );
+      }
+    }
+    throw e;
+  }
+}

package/src/index.ts

@@ -1,6 +1,8 @@
 export * from './conf/index.js';
 export * from './driver/index.js';
 export * from './errors/index.js';
+export * from './decorators/index.js';
+export * from './helpers/index.js';
 
 export * from './Entity.types.js';
 

package/src/testArtifacts.ts

@@ -1,4 +1,6 @@
 import Entity from './Entity.js';
+import { transactional } from './decorators/index.js';
+import { transaction } from './helpers/index.js';
 
 export type TestModelData = {
   name?: string;
@@ -67,6 +69,53 @@ export class TestModel extends Entity<TestModelData> {
       this.$protectedTags = $protectedTags;
     };
   }
+
+  @transactional
+  public async $testTransactionalDecorator(throwError: boolean) {
+    this.$data.string = 'this has been changed';
+
+    if (this.$data.reference) {
+      await this.$data.reference.$wake();
+      this.$data.reference.string = 'this has been changed too';
+      await this.$data.reference.$save();
+    }
+
+    await this.$save();
+
+    if (throwError) {
+      throw Error('An error.');
+    }
+
+    return 'Success.';
+  }
+
+  public async $testTransactionHelper(throwError: boolean) {
+    return await transaction(
+      this.$nymph,
+      'test-transaction',
+      async (nymph) => {
+        this.$setNymph(nymph);
+        this.$data.string = 'this has been changed';
+
+        if (this.$data.reference) {
+          await this.$data.reference.$wake();
+          this.$data.reference.string = 'this has been changed too';
+          await this.$data.reference.$save();
+        }
+
+        await this.$save();
+
+        if (throwError) {
+          throw Error('An error.');
+        }
+
+        return 'Success.';
+      },
+      async (nymph) => {
+        this.$setNymph(nymph);
+      },
+    );
+  }
 }
 
 /**

package/src/testMocks.ts

@@ -8,7 +8,7 @@ import type {
   EntityJson,
 } from './Entity.types.js';
 import { Options, Selector } from './Nymph.types.js';
-import { ClassNotAvailableError } from './errors/index.js';
+import { ClassNotAvailableError, EntityConflictError } from './errors/index.js';
 import Entity from './Entity.js';
 
 const entities: { [k: string]: EntityJson } = {};
@@ -163,7 +163,9 @@ export class MockNymph {
       entity.guid in entities &&
       (entity.mdate ?? 0) < (entities[entity.guid].mdate ?? 0)
     ) {
-      return false;
+      throw new EntityConflictError(
+        "Entity either doesn't exist or is newer in the DB.",
+      );
     }
 
     entity.mdate = Date.now();