mythix-orm 1.7.2 → 1.8.1

package/lib/types/concrete/uuid-v4-type.js

@@ -7,6 +7,51 @@ const { defaultValueFlags } = require('../helpers/default-helpers');
 
 let CALLABLE_PROP_NAMES = [ 'random', 'buffer', 'offset' ];
 
+/// `UUID` (version 4) type.
+///
+/// This represents a string based UUID,
+/// using UUID version 4. The underlying
+/// database type is the same as <see>StringType</see>,
+/// which is usually a "VARCHAR" type.
+///
+/// An optional "prefix" can be specified for this
+/// type, which will allow you to prefix your ids.
+///
+/// This type will automatically decide its own "length"
+/// based on the length of a UUIDV4, plus the length of
+/// any prefix you provide.
+///
+/// See the [uuid](https://www.npmjs.com/package/uuid)
+/// module to properly understand the options for this
+/// field type.
+///
+/// Example:
+///   class UUIDs extends Model {
+///     static fields = {
+///       uuid1: Types.UUIDV4({
+///         prefix: 'USER_',
+///         random: ...,
+///         rng: ...,
+///         buffer: ...,
+///         offset: ...,
+///       }),
+///       uuid2: new Types.UUIDV4Type({
+///         prefix: 'USER_',
+///         ...,
+///       }),
+///       uuidWithDefault: {
+///         type: Types.UUIDV4({ ... }),
+///         defaultValue: Types.UUIDV4.Default.UUIDV4,
+///       },
+///     };
+///   }
+///
+/// Properties:
+///   Default: object = { UUIDV4 }
+///     `UUIDV4` is a method that can be used as the `defaultValue` of a <see>Field</see>
+///     to have this field auto-generate UUIDs for new models.
+///
+/// See: Type
 class UUIDV4Type extends UUIDBaseType {
   static Default = {
     UUIDV4: defaultValueFlags(function(context) {
@@ -23,10 +68,35 @@ class UUIDV4Type extends UUIDBaseType {
     }),
   };
 
+  /// Get the "display" name for this type.
+  ///
+  /// This method is called from <see>Model.toString</see>
+  /// when stringifying the model for representation.
+  ///
+  /// Note:
+  ///   This is also an instance method that can be called from
+  ///   an instance of the type.
+  ///
+  /// Return: string
+  ///   Return the string value `'UUIDV4'`
   static getDisplayName() {
     return 'UUIDV4';
   }
 
+  /// This is an internal method that is used by the
+  /// type. It prepares the arguments needed for the
+  /// [uuid](https://www.npmjs.com/package/uuid) module
+  /// based on the options provided to the type when
+  /// created. It will return arguments that can be
+  /// properly passed to [uuid.v1](https://www.npmjs.com/package/uuid#uuidv4options-buffer-offset).
+  ///
+  /// Return: Array<any>
+  ///   An array of arguments to pass to `uuid.v1`
+  ///
+  /// Arguments:
+  ///   options: object
+  ///     The "options" object provided to the type when
+  ///     it was initially created.
   getArgsForUUID(options) {
     let uuidOptions = {};
 
@@ -53,10 +123,59 @@ class UUIDV4Type extends UUIDBaseType {
     return args;
   }
 
+  /// This is an internal method that is used by the
+  /// type. It validates the arguments that will be passed
+  /// to the [uuid.v4](https://www.npmjs.com/package/uuid#uuidv4options-buffer-offset) method.
+  /// If incorrect options were provided to the type
+  /// when the type was specified, then this will throw
+  /// a validation exception.
+  ///
+  /// Note:
+  ///   The provided "options" are not validated until
+  ///   the first UUID is generated for the first time.
+  ///
+  /// Return: undefined
+  ///
+  /// Arguments:
+  ///   uuidArgs: Array<any>
+  ///     The arguments that will be passed to [uuid.v4](https://www.npmjs.com/package/uuid#uuidv4options-buffer-offset).
+  ///     If an issue is detected than an exception will be thrown.
   validateOptions() {
     // No validation required for V4
   }
 
+  /// Cast provided value to underlying type.
+  ///
+  /// This will cast the incoming value to the
+  /// underlying type of this field, a `UUIDV4`
+  /// string primitive. A `null` or `undefined`
+  /// value will simply be returned.
+  ///
+  /// The provided value will be given to [uuid.validate](https://www.npmjs.com/package/uuid#uuidvalidatestr)
+  /// to validate that it is a correct UUIDV4. If the provided value
+  /// is not a valid UUIDV4, then this method will throw an exception.
+  ///
+  /// If your UUID is prefixed with the `prefix`
+  /// option, then that will be stripped off first
+  /// before the provided value is handed off to
+  /// [uuid.validate](https://www.npmjs.com/package/uuid#uuidvalidatestr)
+  /// for validation. The prefix will be added back after validation.
+  ///
+  /// Note:
+  ///   If a valid UUID is given without a prefix, then the
+  ///   specified prefix (if any) will simply be added to
+  ///   the returned result.
+  ///
+  /// See <see>Type.castToType</see> for a more
+  /// detailed description.
+  ///
+  /// Return: string | null | undefined
+  ///   Return the incoming `value`, cast to this
+  ///   type. `null` and `undefined` are simply
+  ///   returned without casting.
+  ///
+  /// Arguments:
+  ///   context: <see name="CastToTypeContext">Type.castToType</see>
   castToType(args) {
     let { value } = args;
     if (value == null)
@@ -68,6 +187,16 @@ class UUIDV4Type extends UUIDBaseType {
     return this.addPrefix(value);
   }
 
+  /// Check if the provided value is valid.
+  ///
+  /// This will check if the provided value is
+  /// a valid UUIDV4, ignoring any prefix.
+  ///
+  /// Return: boolean
+  ///
+  /// Arguments:
+  ///   value: any
+  ///     The value to check.
   isValidValue(value) {
     if (!Nife.instanceOf(value, 'string'))
       return false;

package/lib/types/concrete/uuid-v5-type.js

@@ -7,6 +7,51 @@ const { defaultValueFlags } = require('../helpers/default-helpers');
 
 let CALLABLE_PROP_NAMES = [ 'name', 'namespace', 'buffer', 'offset' ];
 
+/// `UUID` (version 5) type.
+///
+/// This represents a string based UUID,
+/// using UUID version 5. The underlying
+/// database type is the same as <see>StringType</see>,
+/// which is usually a "VARCHAR" type.
+///
+/// An optional "prefix" can be specified for this
+/// type, which will allow you to prefix your ids.
+///
+/// This type will automatically decide its own "length"
+/// based on the length of a UUIDV5, plus the length of
+/// any prefix you provide.
+///
+/// See the [uuid](https://www.npmjs.com/package/uuid)
+/// module to properly understand the options for this
+/// field type.
+///
+/// Example:
+///   class UUIDs extends Model {
+///     static fields = {
+///       uuid1: Types.UUIDV5({
+///         prefix: 'USER_',
+///         name: ...,
+///         namespace: ...,
+///         buffer: ...,
+///         offset: ...,
+///       }),
+///       uuid2: new Types.UUIDV3Type({
+///         prefix: 'USER_',
+///         ...,
+///       }),
+///       uuidWithDefault: {
+///         type: Types.UUIDV5({ ... }),
+///         defaultValue: Types.UUIDV5.Default.UUIDV5,
+///       },
+///     };
+///   }
+///
+/// Properties:
+///   Default: object = { UUIDV5 }
+///     `UUIDV5` is a method that can be used as the `defaultValue` of a <see>Field</see>
+///     to have this field auto-generate UUIDs for new models.
+///
+/// See: Type
 class UUIDV5Type extends UUIDBaseType {
   static Default = {
     UUIDV5: defaultValueFlags(function(context) {
@@ -23,10 +68,35 @@ class UUIDV5Type extends UUIDBaseType {
     }),
   };
 
+  /// Get the "display" name for this type.
+  ///
+  /// This method is called from <see>Model.toString</see>
+  /// when stringifying the model for representation.
+  ///
+  /// Note:
+  ///   This is also an instance method that can be called from
+  ///   an instance of the type.
+  ///
+  /// Return: string
+  ///   Return the string value `'UUIDV5'`
   static getDisplayName() {
     return 'UUIDV5';
   }
 
+  /// This is an internal method that is used by the
+  /// type. It prepares the arguments needed for the
+  /// [uuid](https://www.npmjs.com/package/uuid) module
+  /// based on the options provided to the type when
+  /// created. It will return arguments that can be
+  /// properly passed to [uuid.v5](https://www.npmjs.com/package/uuid#uuidv5name-namespace-buffer-offset).
+  ///
+  /// Return: Array<any>
+  ///   An array of arguments to pass to `uuid.v5`
+  ///
+  /// Arguments:
+  ///   options: object
+  ///     The "options" object provided to the type when
+  ///     it was initially created.
   getArgsForUUID(options) {
     let uuidOptions = {};
 
@@ -62,6 +132,23 @@ class UUIDV5Type extends UUIDBaseType {
     return args;
   }
 
+  /// This is an internal method that is used by the
+  /// type. It validates the arguments that will be passed
+  /// to the [uuid.v5](https://www.npmjs.com/package/uuid#uuidv5name-namespace-buffer-offset) method.
+  /// If incorrect options were provided to the type
+  /// when the type was specified, then this will throw
+  /// a validation exception.
+  ///
+  /// Note:
+  ///   The provided "options" are not validated until
+  ///   the first UUID is generated for the first time.
+  ///
+  /// Return: undefined
+  ///
+  /// Arguments:
+  ///   uuidArgs: Array<any>
+  ///     The arguments that will be passed to [uuid.v5](https://www.npmjs.com/package/uuid#uuidv5name-namespace-buffer-offset).
+  ///     If an issue is detected than an exception will be thrown.
   validateOptions(uuidArgs) {
     let [ name, namespace ] = uuidArgs;
 
@@ -75,6 +162,38 @@ class UUIDV5Type extends UUIDBaseType {
       throw new Error('UUIDV5Type::Default::UUIDV5: "options.namespace" option is required for the specified type. Try "type: Types.UUIDV5({ namespace: Function | String | Array[16] })" for your type instead.');
   }
 
+  /// Cast provided value to underlying type.
+  ///
+  /// This will cast the incoming value to the
+  /// underlying type of this field, a `UUIDV5`
+  /// string primitive. A `null` or `undefined`
+  /// value will simply be returned.
+  ///
+  /// The provided value will be given to [uuid.validate](https://www.npmjs.com/package/uuid#uuidvalidatestr)
+  /// to validate that it is a correct UUIDV5. If the provided value
+  /// is not a valid UUIDV5, then this method will throw an exception.
+  ///
+  /// If your UUID is prefixed with the `prefix`
+  /// option, then that will be stripped off first
+  /// before the provided value is handed off to
+  /// [uuid.validate](https://www.npmjs.com/package/uuid#uuidvalidatestr)
+  /// for validation. The prefix will be added back after validation.
+  ///
+  /// Note:
+  ///   If a valid UUID is given without a prefix, then the
+  ///   specified prefix (if any) will simply be added to
+  ///   the returned result.
+  ///
+  /// See <see>Type.castToType</see> for a more
+  /// detailed description.
+  ///
+  /// Return: string | null | undefined
+  ///   Return the incoming `value`, cast to this
+  ///   type. `null` and `undefined` are simply
+  ///   returned without casting.
+  ///
+  /// Arguments:
+  ///   context: <see name="CastToTypeContext">Type.castToType</see>
   castToType(args) {
     let { value } = args;
     if (value == null)
@@ -86,6 +205,16 @@ class UUIDV5Type extends UUIDBaseType {
     return this.addPrefix(value);
   }
 
+  /// Check if the provided value is valid.
+  ///
+  /// This will check if the provided value is
+  /// a valid UUIDV5, ignoring any prefix.
+  ///
+  /// Return: boolean
+  ///
+  /// Arguments:
+  ///   value: any
+  ///     The value to check.
   isValidValue(value) {
     if (!Nife.instanceOf(value, 'string'))
       return false;

package/lib/types/concrete/xid-type.js

@@ -5,6 +5,44 @@ const XID                   = require('xid-js');
 const UUIDBaseType          = require('./uuid-base');
 const { defaultValueFlags } = require('../helpers/default-helpers');
 
+/// `XID` type.
+///
+/// This represents a string based XID. The underlying
+/// database type is the same as <see>StringType</see>,
+/// which is usually a "VARCHAR" type.
+///
+/// An optional "prefix" can be specified for this
+/// type, which will allow you to prefix your ids.
+///
+/// This type will automatically decide its own "length"
+/// based on the length of an XID, plus the length of
+/// any prefix you provide.
+///
+/// This type uses the [xid-js](https://www.npmjs.com/package/xid-js)
+/// module to generate XIDs.
+///
+/// Example:
+///   class XIDs extends Model {
+///     static fields = {
+///       xid1: Types.XID({
+///         prefix: 'USER_',
+///       }),
+///       xid2: new Types.XIDType({
+///         prefix: 'USER_',
+///       }),
+///       xidWithDefault: {
+///         type: Types.XID({ ... }),
+///         defaultValue: Types.XID.Default.XID,
+///       },
+///     };
+///   }
+///
+/// Properties:
+///   Default: object = { XID }
+///     `XID` is a method that can be used as the `defaultValue` of a <see>Field</see>
+///     to have this field auto-generate XIDs for new models.
+///
+/// See: Type
 class XIDType extends UUIDBaseType {
   static Default = {
     XID: defaultValueFlags(function(context) {
@@ -16,10 +54,51 @@ class XIDType extends UUIDBaseType {
     }),
   };
 
+  /// Get the "display" name for this type.
+  ///
+  /// This method is called from <see>Model.toString</see>
+  /// when stringifying the model for representation.
+  ///
+  /// Note:
+  ///   This is also an instance method that can be called from
+  ///   an instance of the type.
+  ///
+  /// Return: string
+  ///   Return the string value `'XID'`
   static getDisplayName() {
     return 'XID';
   }
 
+  /// Cast provided value to underlying type.
+  ///
+  /// This will cast the incoming value to the
+  /// underlying type of this field, a `XID`
+  /// string primitive. A `null` or `undefined`
+  /// value will simply be returned.
+  ///
+  /// The provided value will be validated to ensure
+  /// it is a valid base32 XID value.
+  ///
+  /// If your XID is prefixed with the `prefix`
+  /// option, then that will be stripped off first
+  /// before the provided value is validated.
+  /// The prefix will be added back after validation.
+  ///
+  /// Note:
+  ///   If a valid XID is given without a prefix, then the
+  ///   specified prefix (if any) will simply be added to
+  ///   the returned result.
+  ///
+  /// See <see>Type.castToType</see> for a more
+  /// detailed description.
+  ///
+  /// Return: string | null | undefined
+  ///   Return the incoming `value`, cast to this
+  ///   type. `null` and `undefined` are simply
+  ///   returned without casting.
+  ///
+  /// Arguments:
+  ///   context: <see name="CastToTypeContext">Type.castToType</see>
   castToType(args) {
     let { value } = args;
     if (value == null)
@@ -31,6 +110,16 @@ class XIDType extends UUIDBaseType {
     return this.addPrefix(value);
   }
 
+  /// Check if the provided value is valid.
+  ///
+  /// This will check if the provided value is
+  /// a valid XID, ignoring any prefix.
+  ///
+  /// Return: boolean
+  ///
+  /// Arguments:
+  ///   value: any
+  ///     The value to check.
   isValidValue(value) {
     if (!Nife.instanceOf(value, 'string'))
       return false;

package/lib/utils/async-store.d.ts

@@ -0,0 +1,4 @@
+export declare function getContextStore(): any;
+export declare function getContextValue(key: any, defaultValue: any): any;
+export declare function setContextValue(key: any, value: any): void;
+export declare function runInContext(context: any, callback: Function): Promise<any>;

package/lib/utils/async-store.js

@@ -0,0 +1,60 @@
+'use strict';
+
+let globalAsyncStore;
+
+try {
+  const { AsyncLocalStorage } = require('async_hooks');
+  globalAsyncStore = new AsyncLocalStorage();
+} catch (error) {
+  globalAsyncStore = {
+    getStore: () => undefined,
+    run:      (context, callback) => callback(),
+  };
+}
+
+function getContextStore() {
+  return globalAsyncStore.getStore();
+}
+
+function getContextValue(key, defaultValue) {
+  let store = globalAsyncStore.getStore();
+  while (store) {
+    let { context } = store;
+    if (!context.has(key)) {
+      store = store.parent;
+      continue;
+    }
+
+    return context.get(key);
+  }
+
+  return defaultValue;
+}
+
+function setContextValue(key, value) {
+  let store = globalAsyncStore.getStore();
+  if (!store || !store.context)
+    return;
+
+  return store.context.set(key, value);
+}
+
+function runInContext(context, callback) {
+  return new Promise((resolve, reject) => {
+    globalAsyncStore.run({ parent: globalAsyncStore.getStore(), context }, async () => {
+      try {
+        let result = await callback();
+        resolve(result);
+      } catch (error) {
+        reject(error);
+      }
+    });
+  });
+}
+
+module.exports = {
+  getContextValue,
+  setContextValue,
+  runInContext,
+  getContextStore,
+};

package/lib/utils/index.d.ts

@@ -4,3 +4,5 @@ export * from './model-utils';
 export * as ModelUtils from './model-utils';
 export * from './query-utils';
 export * as QueryUtils from './query-utils';
+export * from './async-store';
+export * as AsyncStore from './async-store';

package/lib/utils/index.js

@@ -3,6 +3,7 @@
 const MiscUtils   = require('./misc-utils');
 const ModelUtils  = require('./model-utils');
 const QueryUtils  = require('./query-utils');
+const AsyncStore  = require('./async-store');
 
 const {
   collect,
@@ -32,10 +33,18 @@ const {
   generateQueryFromFilter,
 } = QueryUtils;
 
+const {
+  getContextStore,
+  getContextValue,
+  setContextValue,
+  runInContext,
+} = AsyncStore;
+
 module.exports = {
   MiscUtils,
   ModelUtils,
   QueryUtils,
+  AsyncStore,
 
   // MiscUtils
   collect,
@@ -61,4 +70,10 @@ module.exports = {
   // QueryUtils
   parseFilterFieldAndOperator,
   generateQueryFromFilter,
+
+  // AsyncStore
+  getContextStore,
+  getContextValue,
+  setContextValue,
+  runInContext,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mythix-orm",
-  "version": "1.7.2",
+  "version": "1.8.1",
   "description": "ORM for Mythix framework",
   "main": "lib/index",
   "type": "commonjs",