@nymphjs/nymph 1.0.0-beta.1 → 1.0.0-beta.100

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'
@@ -9,105 +9,228 @@ export type NymphEventType =
   | 'beforeGetEntities'
   | 'beforeSaveEntity'
   | 'afterSaveEntity'
+  | 'failedSaveEntity'
   | 'beforeDeleteEntity'
   | 'afterDeleteEntity'
+  | 'failedDeleteEntity'
   | 'beforeDeleteEntityByID'
   | 'afterDeleteEntityByID'
+  | 'failedDeleteEntityByID'
   | 'beforeNewUID'
   | 'afterNewUID'
+  | 'failedNewUID'
   | 'beforeSetUID'
   | 'afterSetUID'
+  | 'failedSetUID'
   | 'beforeRenameUID'
   | 'afterRenameUID'
+  | 'failedRenameUID'
   | 'beforeDeleteUID'
-  | 'afterDeleteUID';
+  | 'afterDeleteUID'
+  | 'failedDeleteUID'
+  | 'beforeStartTransaction'
+  | 'afterStartTransaction'
+  | 'beforeCommitTransaction'
+  | 'afterCommitTransaction'
+  | 'beforeRollbackTransaction'
+  | 'afterRollbackTransaction';
 export type NymphConnectCallback = (
   nymph: Nymph,
-  result: Promise<boolean>
-) => void;
+  result: Promise<boolean>,
+) => Promise<void>;
 export type NymphDisconnectCallback = (
   nymph: Nymph,
-  result: Promise<boolean>
-) => void;
-/** The NymphQueryCallback will be called on both top level and qref queries. */
+  result: Promise<boolean>,
+) => Promise<void>;
+/**
+ * The NymphQueryCallback will be called on both top level and qref queries.
+ *
+ * This is the only callback that is not asynchronous.
+ *
+ * This also isn't necessarily run on every "query". It is run before a database
+ * query for an entity, but it is not run during PubSub entity change
+ * propagation. Therefore, it shouldn't do anything _entity_ specific, instead
+ * it should be _query_ specific. For example, throw an error if the user is not
+ * permitted to run the query at all.
+ */
 export type NymphQueryCallback = (
   nymph: Nymph,
   options: Options,
-  selectors: FormattedSelector[]
+  selectors: FormattedSelector[],
 ) => void;
 export type NymphBeforeGetEntityCallback = (
   nymph: Nymph,
   options: Options,
-  selectors: Selector[]
-) => void;
+  selectors: Selector[],
+) => Promise<void>;
 export type NymphBeforeGetEntitiesCallback = (
   nymph: Nymph,
   options: Options,
-  selectors: Selector[]
-) => void;
+  selectors: Selector[],
+) => Promise<void>;
 export type NymphBeforeSaveEntityCallback = (
   nymph: Nymph,
-  entity: EntityInterface
-) => void;
+  entity: EntityInterface,
+) => Promise<void>;
 export type NymphAfterSaveEntityCallback = (
   nymph: Nymph,
-  result: Promise<boolean>
-) => void;
+  result: Promise<boolean>,
+) => Promise<void>;
+export type NymphFailedSaveEntityCallback = (
+  nymph: Nymph,
+  error: any,
+) => Promise<void>;
 export type NymphBeforeDeleteEntityCallback = (
   nymph: Nymph,
-  entity: EntityInterface
-) => void;
+  entity: EntityInterface,
+) => Promise<void>;
 export type NymphAfterDeleteEntityCallback = (
   nymph: Nymph,
-  result: Promise<boolean>
-) => void;
+  result: Promise<boolean>,
+) => Promise<void>;
+export type NymphFailedDeleteEntityCallback = (
+  nymph: Nymph,
+  error: any,
+) => Promise<void>;
 export type NymphBeforeDeleteEntityByIDCallback = (
   nymph: Nymph,
   guid: string,
-  className?: string
-) => void;
+  className?: string,
+) => Promise<void>;
 export type NymphAfterDeleteEntityByIDCallback = (
   nymph: Nymph,
-  result: Promise<boolean>
-) => void;
-export type NymphBeforeNewUIDCallback = (nymph: Nymph, name: string) => void;
+  result: Promise<boolean>,
+) => Promise<void>;
+export type NymphFailedDeleteEntityByIDCallback = (
+  nymph: Nymph,
+  error: any,
+) => Promise<void>;
+export type NymphBeforeNewUIDCallback = (
+  nymph: Nymph,
+  name: string,
+) => Promise<void>;
 export type NymphAfterNewUIDCallback = (
   nymph: Nymph,
-  result: Promise<number | null>
-) => void;
+  result: Promise<number | null>,
+) => Promise<void>;
+export type NymphFailedNewUIDCallback = (
+  nymph: Nymph,
+  error: any,
+) => Promise<void>;
 export type NymphBeforeSetUIDCallback = (
   nymph: Nymph,
   name: string,
-  value: number
-) => void;
+  value: number,
+) => Promise<void>;
 export type NymphAfterSetUIDCallback = (
   nymph: Nymph,
-  result: Promise<boolean>
-) => void;
+  result: Promise<boolean>,
+) => Promise<void>;
+export type NymphFailedSetUIDCallback = (
+  nymph: Nymph,
+  error: any,
+) => Promise<void>;
 export type NymphBeforeRenameUIDCallback = (
   nymph: Nymph,
   oldName: string,
-  newName: string
-) => void;
+  newName: string,
+) => Promise<void>;
 export type NymphAfterRenameUIDCallback = (
   nymph: Nymph,
-  result: Promise<boolean>
-) => void;
-export type NymphBeforeDeleteUIDCallback = (nymph: Nymph, name: string) => void;
+  result: Promise<boolean>,
+) => Promise<void>;
+export type NymphFailedRenameUIDCallback = (
+  nymph: Nymph,
+  error: any,
+) => Promise<void>;
+export type NymphBeforeDeleteUIDCallback = (
+  nymph: Nymph,
+  name: string,
+) => Promise<void>;
 export type NymphAfterDeleteUIDCallback = (
   nymph: Nymph,
-  result: Promise<boolean>
-) => void;
+  result: Promise<boolean>,
+) => Promise<void>;
+export type NymphFailedDeleteUIDCallback = (
+  nymph: Nymph,
+  error: any,
+) => Promise<void>;
+export type NymphBeforeStartTransactionCallback = (
+  nymph: Nymph,
+  name: string,
+) => Promise<void>;
+export type NymphAfterStartTransactionCallback = (
+  nymph: Nymph,
+  name: string,
+  result: Nymph,
+) => Promise<void>;
+export type NymphBeforeCommitTransactionCallback = (
+  nymph: Nymph,
+  name: string,
+) => Promise<void>;
+export type NymphAfterCommitTransactionCallback = (
+  nymph: Nymph,
+  name: string,
+  result: boolean,
+) => Promise<void>;
+export type NymphBeforeRollbackTransactionCallback = (
+  nymph: Nymph,
+  name: string,
+) => Promise<void>;
+export type NymphAfterRollbackTransactionCallback = (
+  nymph: Nymph,
+  name: string,
+  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.
+   */
+  sort?: 'cdate' | 'mdate' | string;
+  /**
+   * 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;
+  /**
+   * 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;
 };
 
@@ -134,6 +257,9 @@ type PrimitiveSelector = {
   contain?: [string, any];
   '!contain'?: PrimitiveSelector['contain'];
 
+  search?: [string, string];
+  '!search'?: PrimitiveSelector['search'];
+
   match?: [string, string];
   '!match'?: PrimitiveSelector['match'];
 
@@ -189,6 +315,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']>;
 
@@ -244,6 +373,9 @@ export type FormattedSelector = {
   contain?: PrimitiveSelector['contain'][];
   '!contain'?: PrimitiveSelector['contain'][];
 
+  search?: PrimitiveSelector['search'][];
+  '!search'?: PrimitiveSelector['search'][];
+
   match?: PrimitiveSelector['match'][];
   '!match'?: PrimitiveSelector['match'][];
 
@@ -293,9 +425,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/d.ts

@@ -21,4 +21,29 @@ export interface Config {
    * 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;
 }

package/src/conf/defaults.ts

@@ -1,8 +1,41 @@
-import { Config } from './d';
+import createDebug, { type Debugger } from 'debug';
+
+import { Config } from './d.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,4 @@
-export { Config } from './d';
+export { Config } from './d.js';
 
-import defaults from './defaults';
+import defaults from './defaults.js';
 export { defaults as ConfigDefaults };