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

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.js';
+import type Nymph from './Nymph.js';
 
 export type NymphEventType =
   | 'connect'
@@ -36,11 +36,11 @@ export type NymphEventType =
   | 'afterRollbackTransaction';
 export type NymphConnectCallback = (
   nymph: Nymph,
-  result: Promise<boolean>
+  result: Promise<boolean>,
 ) => Promise<void>;
 export type NymphDisconnectCallback = (
   nymph: Nymph,
-  result: Promise<boolean>
+  result: Promise<boolean>,
 ) => Promise<void>;
 /**
  * The NymphQueryCallback will be called on both top level and qref queries.
@@ -56,142 +56,192 @@ export type NymphDisconnectCallback = (
 export type NymphQueryCallback = (
   nymph: Nymph,
   options: Options,
-  selectors: FormattedSelector[]
+  selectors: FormattedSelector[],
 ) => void;
 export type NymphBeforeGetEntityCallback = (
   nymph: Nymph,
   options: Options,
-  selectors: Selector[]
+  selectors: Selector[],
 ) => Promise<void>;
 export type NymphBeforeGetEntitiesCallback = (
   nymph: Nymph,
   options: Options,
-  selectors: Selector[]
+  selectors: Selector[],
 ) => Promise<void>;
 export type NymphBeforeSaveEntityCallback = (
   nymph: Nymph,
-  entity: EntityInterface
+  entity: EntityInterface,
 ) => Promise<void>;
 export type NymphAfterSaveEntityCallback = (
   nymph: Nymph,
-  result: Promise<boolean>
+  result: Promise<boolean>,
 ) => Promise<void>;
 export type NymphFailedSaveEntityCallback = (
   nymph: Nymph,
-  error: any
+  error: any,
 ) => Promise<void>;
 export type NymphBeforeDeleteEntityCallback = (
   nymph: Nymph,
-  entity: EntityInterface
+  entity: EntityInterface,
 ) => Promise<void>;
 export type NymphAfterDeleteEntityCallback = (
   nymph: Nymph,
-  result: Promise<boolean>
+  result: Promise<boolean>,
 ) => Promise<void>;
 export type NymphFailedDeleteEntityCallback = (
   nymph: Nymph,
-  error: any
+  error: any,
 ) => Promise<void>;
 export type NymphBeforeDeleteEntityByIDCallback = (
   nymph: Nymph,
   guid: string,
-  className?: string
+  className?: string,
 ) => Promise<void>;
 export type NymphAfterDeleteEntityByIDCallback = (
   nymph: Nymph,
-  result: Promise<boolean>
+  result: Promise<boolean>,
 ) => Promise<void>;
 export type NymphFailedDeleteEntityByIDCallback = (
   nymph: Nymph,
-  error: any
+  error: any,
 ) => Promise<void>;
 export type NymphBeforeNewUIDCallback = (
   nymph: Nymph,
-  name: string
+  name: string,
 ) => Promise<void>;
 export type NymphAfterNewUIDCallback = (
   nymph: Nymph,
-  result: Promise<number | null>
+  result: Promise<number | null>,
 ) => Promise<void>;
 export type NymphFailedNewUIDCallback = (
   nymph: Nymph,
-  error: any
+  error: any,
 ) => Promise<void>;
 export type NymphBeforeSetUIDCallback = (
   nymph: Nymph,
   name: string,
-  value: number
+  value: number,
 ) => Promise<void>;
 export type NymphAfterSetUIDCallback = (
   nymph: Nymph,
-  result: Promise<boolean>
+  result: Promise<boolean>,
 ) => Promise<void>;
 export type NymphFailedSetUIDCallback = (
   nymph: Nymph,
-  error: any
+  error: any,
 ) => Promise<void>;
 export type NymphBeforeRenameUIDCallback = (
   nymph: Nymph,
   oldName: string,
-  newName: string
+  newName: string,
 ) => Promise<void>;
 export type NymphAfterRenameUIDCallback = (
   nymph: Nymph,
-  result: Promise<boolean>
+  result: Promise<boolean>,
 ) => Promise<void>;
 export type NymphFailedRenameUIDCallback = (
   nymph: Nymph,
-  error: any
+  error: any,
 ) => Promise<void>;
 export type NymphBeforeDeleteUIDCallback = (
   nymph: Nymph,
-  name: string
+  name: string,
 ) => Promise<void>;
 export type NymphAfterDeleteUIDCallback = (
   nymph: Nymph,
-  result: Promise<boolean>
+  result: Promise<boolean>,
 ) => Promise<void>;
 export type NymphFailedDeleteUIDCallback = (
   nymph: Nymph,
-  error: any
+  error: any,
 ) => Promise<void>;
 export type NymphBeforeStartTransactionCallback = (
   nymph: Nymph,
-  name: string
+  name: string,
 ) => Promise<void>;
 export type NymphAfterStartTransactionCallback = (
   nymph: Nymph,
   name: string,
-  result: Nymph
+  result: Nymph,
 ) => Promise<void>;
 export type NymphBeforeCommitTransactionCallback = (
   nymph: Nymph,
-  name: string
+  name: string,
 ) => Promise<void>;
 export type NymphAfterCommitTransactionCallback = (
   nymph: Nymph,
   name: string,
-  result: boolean
+  result: boolean,
 ) => Promise<void>;
 export type NymphBeforeRollbackTransactionCallback = (
   nymph: Nymph,
-  name: string
+  name: string,
 ) => Promise<void>;
 export type NymphAfterRollbackTransactionCallback = (
   nymph: Nymph,
   name: string,
-  result: boolean
+  result: boolean,
 ) => Promise<void>;
 
 export type Options<T extends EntityConstructor = EntityConstructor> = {
+  /**
+   * The Entity class to query.
+   */
   class?: T;
+  /**
+   * The limit of entities to be returned. Not needed when using `getEntity`, as
+   * it always returns only one.
+   */
   limit?: number;
+  /**
+   * The offset from the first matching entity, in order, to start retrieving.
+   */
   offset?: number;
+  /**
+   * If true, entities will be retrieved from newest to oldest/largest to
+   * smallest (with regard to `sort`).
+   */
   reverse?: boolean;
-  sort?: 'cdate' | 'mdate';
-  return?: 'entity' | 'guid' | 'count';
+  /**
+   * How to sort the entities. Should be "cdate", "mdate", or the name of a
+   * property.
+   *
+   * When null, the result set will not be sorted in any particular way. It's
+   * really up to the DB how the results are returned. In this case, limit and
+   * offset may work for pagination, but shouldn't be relied on.
+   */
+  sort?: 'cdate' | 'mdate' | string | null;
+  /**
+   * 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' | '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.)
+   */
   source?: string;
+  /**
+   * If true, Nymph will skip the cache and retrieve the entity from the DB.
+   */
   skipCache?: boolean;
+  /**
+   * The level(s) of access control requested.
+   *
+   * Limiting the access control can significantly improve the performance of
+   * the query.
+   */
+  acRequest?: TilmeldAccessRequest;
+  /**
+   * If true, Tilmeld will not filter returned entities according to access
+   * controls. (If Tilmeld is installed.) (This is always set to false by the
+   * REST endpoint and PubSub server.)
+   */
   skipAc?: boolean;
 };
 
@@ -218,6 +268,9 @@ type PrimitiveSelector = {
   contain?: [string, any];
   '!contain'?: PrimitiveSelector['contain'];
 
+  search?: [string, string];
+  '!search'?: PrimitiveSelector['search'];
+
   match?: [string, string];
   '!match'?: PrimitiveSelector['match'];
 
@@ -273,6 +326,9 @@ export type Selector = {
   contain?: Clause<OrWithTime<PrimitiveSelector['contain']>>;
   '!contain'?: Clause<OrWithTime<PrimitiveSelector['contain']>>;
 
+  search?: Clause<PrimitiveSelector['search']>;
+  '!search'?: Clause<PrimitiveSelector['search']>;
+
   match?: Clause<PrimitiveSelector['match']>;
   '!match'?: Clause<PrimitiveSelector['match']>;
 
@@ -328,6 +384,9 @@ export type FormattedSelector = {
   contain?: PrimitiveSelector['contain'][];
   '!contain'?: PrimitiveSelector['contain'][];
 
+  search?: PrimitiveSelector['search'][];
+  '!search'?: PrimitiveSelector['search'][];
+
   match?: PrimitiveSelector['match'][];
   '!match'?: PrimitiveSelector['match'][];
 
@@ -370,6 +429,50 @@ export enum TilmeldAccessLevels {
   FULL_ACCESS = 4,
 }
 
+export enum TilmeldAccessRequest {
+  /**
+   * The default level, any possible entity readable by the user.
+   *
+   * This is the same as or-ing together all of the levels listed below.
+   */
+  ALL_LEVELS = 0,
+  /**
+   * Owned by and accessible to the user.
+   *
+   * This is always enabled, so not including it has no effect. It's here to
+   * allow the selection of _only_ user owned entities.
+   */
+  USER_OWNED = 1,
+  /**
+   * Owned by and accessible to the user's primary group.
+   */
+  PRIMARY_GROUP_OWNED = 2,
+  /**
+   * Owned by and accessible to one of the user's secondary groups.
+   */
+  SECONDARY_GROUP_OWNED = 4,
+  /**
+   * The user is listed in an access control list.
+   */
+  USER_ACCESSIBLE = 8,
+  /**
+   * The user's primary group is listed in an access control list.
+   */
+  PRIMARY_GROUP_ACCESSIBLE = 16,
+  /**
+   * One of the user's secondary groups is listed in an access control list.
+   */
+  SECONDARY_GROUP_ACCESSIBLE = 32,
+  /**
+   * The entity is accessible to any user.
+   */
+  OTHER_ACCESSIBLE = 64,
+  /**
+   * The entity is not owned by anyone.
+   */
+  UNOWNED = 128,
+}
+
 export interface TilmeldInterface {
   nymph: Nymph;
   request: any;
@@ -377,9 +480,12 @@ export interface TilmeldInterface {
   init(nymph: Nymph): void;
   clone(): TilmeldInterface;
   gatekeeper(ability?: string): boolean;
-  authenticate(): void;
+  authenticate(skipXsrfToken?: boolean, skipRenew?: boolean): Promise<boolean>;
   clearSession(): void;
   extractToken(token: string): Promise<any>;
-  fillSession(user: any): void;
-  checkClientUIDPermissions(name: string, type?: TilmeldAccessLevels): boolean;
+  fillSession(user: any): Promise<void>;
+  checkClientUIDPermissions(
+    name: string,
+    type?: TilmeldAccessLevels,
+  ): Promise<boolean>;
 }

package/src/conf/defaults.ts

@@ -1,8 +1,41 @@
-import { Config } from './d';
+import createDebug, { type Debugger } from 'debug';
+
+import type { Config } from './index.js';
+
+const debuggers: {
+  [k: string]: { info: Debugger; log: Debugger; error: Debugger };
+} = {};
+
+function getDebuggers(source: string) {
+  if (source in debuggers) {
+    return debuggers[source];
+  }
+
+  debuggers[source] = {
+    info: createDebug(`nymphjs:info:${source}`),
+    log: createDebug(`nymphjs:log:${source}`),
+    error: createDebug(`nymphjs:error:${source}`),
+  };
+
+  debuggers[source].info.log = console.info.bind(console);
+  debuggers[source].log.log = console.log.bind(console);
+
+  return debuggers[source];
+}
 
 export default {
   cache: false,
   cacheThreshold: 4,
   cacheLimit: 50,
   emptyListError: false,
+  updateMDate: true,
+  debugInfo: (source, message) => {
+    getDebuggers(source).info(message);
+  },
+  debugLog: (source, message) => {
+    getDebuggers(source).log(message);
+  },
+  debugError: (source, message) => {
+    getDebuggers(source).error(message);
+  },
 } as Config;

package/src/conf/index.ts

@@ -1,4 +1,52 @@
-export { Config } from './d';
+/**
+ * Nymph Config
+ */
+export interface Config {
+  /**
+   * Cache recently retrieved entities to speed up database queries. Uses more
+   * memory.
+   */
+  cache: boolean;
+  /**
+   * Cache entities after they're accessed this many times.
+   */
+  cacheThreshold: number;
+  /**
+   * The number of recently retrieved entities to cache. If you're running out
+   * of memory, try lowering this value. 0 means unlimited.
+   */
+  cacheLimit: number;
+  /**
+   * When querying for multiple entities with NymphREST, if the list is empty,
+   * return a 404 error.
+   */
+  emptyListError: boolean;
+  /**
+   * Whether to update the mdate property when saving an entity.
+   *
+   * You should probably only set this to false if you're doing migrations. Some
+   * things depend on having updated mdates (like conflict detection to avoid
+   * lost updates).
+   *
+   * If you set this to a number, that amount of milliseconds will be added to
+   * the mdate on any entities that are saved. This should solve the lost update
+   * problem when set to a small number (~1000), and keep mdates relatively
+   * unchanged.
+   */
+  updateMDate: boolean | number;
+  /**
+   * A function to log info messages. By default, uses the `debug` package.
+   */
+  debugInfo: (source: string, message: string) => void;
+  /**
+   * A function to log debug messages. By default, uses the `debug` package.
+   */
+  debugLog: (source: string, message: string) => void;
+  /**
+   * A function to log error messages. By default, uses the `debug` package.
+   */
+  debugError: (source: string, message: string) => void;
+}
 
-import defaults from './defaults';
+import defaults from './defaults.js';
 export { defaults as ConfigDefaults };

package/src/decorators/index.ts

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

package/src/decorators/transactional.ts

@@ -0,0 +1,63 @@
+import { nanoid } from '@nymphjs/guid';
+
+import Entity from '../Entity.js';
+
+/**
+ * A decorator that runs the decorated method inside a transaction.
+ *
+ * If the method resolves, the transaction is committed. If the method throws,
+ * the transaction is rolled back.
+ *
+ * Uses $setNymph to set the transactional instance of Nymph on the entity and
+ * return to the original instance after the transaction is committed or rolled
+ * back.
+ */
+export function transactional(
+  target: (...args: any[]) => Promise<any>,
+  context: ClassMethodDecoratorContext,
+) {
+  const name = String(context.name);
+  return async function (this: Entity, ...args: unknown[]) {
+    const transactionName = `${name}-${nanoid()}`;
+    const nymph = this.$nymph;
+    nymph.config.debugInfo(
+      'nymph:transactional',
+      `Starting transaction ${transactionName}`,
+    );
+    const tnymph = await nymph.startTransaction(transactionName);
+    this.$setNymph(tnymph);
+    let committed = false;
+    let result: any;
+    try {
+      result = await target.apply(this, args);
+      nymph.config.debugInfo(
+        'nymph:transactional',
+        `Committing transaction ${transactionName}`,
+      );
+      committed = await tnymph.commit(transactionName);
+    } catch (e: any) {
+      try {
+        nymph.config.debugInfo(
+          'nymph:transactional',
+          `Rolling back transaction ${transactionName}, reason: ${e.message}`,
+        );
+        await tnymph.rollback(transactionName);
+      } catch (e: any) {
+        nymph.config.debugError(
+          'nymph:transactional',
+          `Rollback of transaction ${transactionName} failed, reason: ${e.message}`,
+        );
+      }
+      this.$setNymph(nymph);
+      throw e;
+    }
+
+    this.$setNymph(nymph);
+
+    if (!committed) {
+      throw new Error('Transaction could not be committed.');
+    }
+
+    return result;
+  };
+}