mythix-orm 1.11.6 → 1.12.0

package/lib/types/helpers/default-helpers.js

@@ -1,3 +1,60 @@
+///! Import `const { Types: { Helpers } } = require('mythix-orm');`
+///!
+///! Helpers are a set of utilities used to assist with
+///! `defaultValue` attributes on model fields.
+///!
+///! Default values for fields in Mythix ORM are generally used in
+///! two different places: As column values directly, or as `DEFAULT VALUE`
+///! for columns when defining tables in the database. When creating tables
+///! the `defaultValue` of a field will generally only ever be used if it
+///! has the `remote` flag set. Otherwise, Mythix ORM simply provides the
+///! `defaultValue` to the database directly during `INSERT` and `UPDATE`
+///! operations.
+///!
+///! ```javascript
+///! const { Model, Types } = require('mythix-orm');
+///!
+///! class TestModel extends Model {
+///!   static fields = {
+///!     myCustomDate: {
+///!       type: Types.STRING(32),
+///!       // Inform Mythix ORM that our `defaultValue` should be
+///!       // applied on every `UPDATE` operation... even if the
+///!       // field already has a value.
+///!       defaultValue: Types.Helpers.defaultValueFlags(() => {
+///!         return (new Date()).toISOString();
+///!       }, { onUpdate: true }),
+///!       allowNull: false,
+///!       index: true,
+///!     }
+///!   };
+///! }
+///! ```
+///!
+///! Properties:
+///!   FLAG_ON_INITIALIZE: number = 0x01
+///!     This flag informs Mythix ORM that the `defaultValue` should
+///!     be fetched and used as soon as a model instance is first
+///!     initialized.
+///!   FLAG_ON_INSERT: number = 0x02
+///!     This flag informs Mythix ORM that the `defaultValue` should
+///!     only be used on `INSERT` operations.
+///!   FLAG_ON_UPDATE: number = 0x04
+///!     This flag informs Mythix ORM that the `defaultValue` should
+///!     only be used on `UPDATE` operations. This is used for example
+///!     by `Types.DATE.Defaults.NOW.UPDATE`.
+///!   FLAG_ON_STORE: number = 0x06
+///!     This flag informs Mythix ORM that the `defaultValue` should
+///!     only be used on `INSERT` and `UPDATE` operations.
+///!   FLAG_LITERAL: number = 0x08
+///!     This flag informs Mythix ORM that the `defaultValue` is intended
+///!     to be a literal value, and should not be escaped.
+///!   FLAG_REMOTE: number = 0x10
+///!     This flag informs Mythix ORM that the `defaultValue` is provided
+///!     by the database itself. For example the `Types.BIGINT.Defaults.AUTO_INCREMENT`
+///!     type uses this flag.
+///!
+///! DocScope: Helpers
 'use strict';
 
 const FLAG_ON_INITIALIZE  = 0x01;
@@ -7,6 +64,46 @@ const FLAG_ON_STORE       = FLAG_ON_INSERT | FLAG_ON_UPDATE;
 const FLAG_LITERAL        = 0x08;
 const FLAG_REMOTE         = 0x10;
 
+/// Give a `defaultValue` method certain flags to
+/// assist Mythix ORM in working with a field's
+/// `defaultValue`.
+///
+/// `defaultValue` flags change the way a `defaultValue`
+/// for a field behaves. For example, if the `FLAG_LITERAL`
+/// is set, then the database will not escape the default value.
+///
+/// By default, all `defaultValue` attributes on fields (that
+/// are methods) have the flags `FLAG_ON_INITIALIZE`, which
+/// simply tells Mythix ORM to call the `defaultValue` method
+/// and assign the result to the field as soon as the model is
+/// instantiated. This is the default behavior of all `defaultValue`
+/// attributes... unless the defined flags change that default
+/// behavior. As soon as any flag is set on a `defaultValue` method,
+/// the `FLAG_ON_INITIALIZE` value will be cleared.
+///
+/// This adds an attribute named `mythixFlags` to
+/// the provided method. This attribute is then
+/// used by Mythix ORM to know what to do with the
+/// `defaultValue` method provided on a field.
+///
+/// Arguments:
+///   func: Function
+///     The `defaultValue` function to apply flags to.
+///   flags: object
+///     An object, specifying which flags to enable
+///     or disable. The allowed properties are listed in
+///     the table below.
+///     | Option | Type | Default Value | Description |
+///     | ------------- | ---- | ------------- | ----------- |
+///     | `onInitialize` | `boolean` | `true` | If `true`, then assign the `defaultValue` as soon as a model is instantiated. |
+///     | `onInsert` | `boolean` | `false` | If `true`, then only assign the `defaultValue` when an `INSERT` operation is being executed. |
+///     | `onUpdate` | `boolean` | `false` | If `true`, then only assign the `defaultValue` when an `UPDATE` operation is being executed. |
+///     | `onStore` | `boolean` | `false` | If `true`, then only assign the `defaultValue` when an `INSERT` or `UPDATE` operation is being executed. |
+///     | `literal` | `boolean` | `false` | If `true`, then inform Mythix ORM that the value is a literal, and not to escape it. |
+///     | `remote` | `boolean` | `false` | If `true`, then inform Mythix ORM that the value is provided by the database itself. |
+///
+/// Return: Function
+///   The method provided, with a new `mythixFlags` assigned to it.
 function defaultValueFlags(func, _flagsObj) {
   let flags = FLAG_ON_INITIALIZE;
   let flagsObj = _flagsObj || {};
@@ -36,6 +133,15 @@ function defaultValueFlags(func, _flagsObj) {
   return func;
 }
 
+/// Fetch the `mythixFlags` attribute on the provided
+/// function. If none is found, or no method is provided,
+/// then the value `0` will be returned instead.
+///
+/// Return: number
+///   The `defaultValue` flags as a bitmask. If none is found, or no
+///   method is provided, then `0` will be returned instead.
+///
+/// See: Helpers.defaultValueFlags
 function getDefaultValueFlags(func) {
   if (!func)
     return 0;
@@ -43,6 +149,24 @@ function getDefaultValueFlags(func) {
   return func.mythixFlags || 0;
 }
 
+/// Check if the provided `defaultValue` method has
+/// specific flags set. The flags are provided via
+/// their name.
+///
+/// Arguments:
+///   func: Function
+///     The `defaultValue` function to check.
+///   checkFlags: Array<string>
+///     The flags to check. Acceptable values are:
+///     `[ 'onInitialize', 'onInsert', 'onUpdate', 'onStore', 'literal', 'remote' ]`
+///
+/// Return: boolean
+///   Return `true` if all provided `checkFlags` are `true`. If any
+///   provided flag results in `false`, then the method will return
+///   `false`. In short, all provided flags must be `true`, otherwise
+///   `false` is returned.
+///
+/// See: Helpers.defaultValueFlags
 function checkDefaultValueFlags(func, checkFlags) {
   if (!checkFlags || !checkFlags.length || !func)
     return false;

package/lib/types/type.js

@@ -8,6 +8,20 @@ class Type {
     return '<UNKNOWN>';
   }
 
+  /// Get the "display name" for this type instance.
+  ///
+  /// This will return a "human friendly" name for the type,
+  /// generally used for logging or debugging. It will change
+  /// based on the type it is called upon. For example, a
+  /// <see>BooleanType</see> will return the string value `'BOOLEAN'`.
+  ///
+  /// Note:
+  ///   This method is also a static method on the type class.
+  ///
+  /// Return: string
+  ///   A string representing the type. This is not the same as
+  ///   the database equivalent type. Rather, it is simply used
+  ///   to represent the type for logging or debugging.
   getDisplayName() {
     return this.constructor.getDisplayName();
   }
@@ -18,6 +32,18 @@ class Type {
     return this;
   };
 
+  /// Use this method to check if a class
+  /// is a Mythix ORM field type. It will return
+  /// `true` if the provided value is a class
+  /// that inherits from <see>Type</see>, or
+  /// if the provided value has an attribute
+  /// named `_isMythixFieldType` that is truthy.
+  ///
+  /// Return: boolean
+  ///
+  /// Arguments:
+  ///   value: Function
+  ///     Value to check.
   static isTypeClass(value) {
     if (!value)
       return false;
@@ -31,6 +57,22 @@ class Type {
     return false;
   }
 
+  /// Check to see if the provided value is
+  /// an *instance* of a Mythix ORM <see>Type</see>.
+  /// Unlike <see>Type.static isTypeClass</see>, which
+  /// checks if a *class* is a <see>Type</see>, this will check
+  /// to see if an *instance* is an instance of a
+  /// Mythix ORM <see>Type</see>. It will return
+  /// `true` if the provided value is an `instanceof`
+  /// <see>Type</see>, or if the value's `constructor`
+  /// property has a truthy `_isMythixFieldType` property
+  /// (`value.constructor._isMythixFieldType`)
+  ///
+  /// Return: boolean
+  ///
+  /// Arguments:
+  ///   value: any
+  ///     Value to check
   static isType(value) {
     if (!value)
       return false;
@@ -44,10 +86,42 @@ class Type {
     return false;
   }
 
+  /// Check to see if the provided type is the same as this type.
+  ///
+  /// This checks if the two types are the same type by comparing
+  /// the type names. For example, a `Types.BooleanType.isSameType(new BooleanType())`
+  /// would return `true`.
+  ///
+  /// Arguments:
+  ///   value: <see>Type</see>
+  ///     A type instance to check. This must be a type instance, not a type class.
+  ///
+  /// Return: boolean
+  ///   Return `true` if the provided `value` is the same type instance as this type class.
+  ///   Return `false` otherwise. Similarity is based on the name of the types. If the class
+  ///   names between the two match, then the types are considered the same type.
   static isSameType(value) {
     return (this.isType(value) && value.constructor && value.constructor.name === this.name);
   }
 
+  /// Instantiate this field type.
+  ///
+  /// This method will instantiate the type class it
+  /// is called from. It won't instantiate the type if
+  /// it is already instantiated, and it will call the
+  /// type wrapper if one was provided (see <see>Type.static wrapConstructor</see>).
+  /// It may not need to instantiate the type if the user already
+  /// did so (for example `type: new Types.StringType()`,
+  /// or `type: Types.STRING()`). It may need to instantiate
+  /// however if the user didn't do so, for example `type: Types.StringType`,
+  /// or `type: Types.STRING`.
+  ///
+  /// Note:
+  ///   If the type is already instantiated, then it will be
+  ///   cloned instead using <see>Type.clone</see>.
+  ///
+  /// Return: <see>Type</see>
+  ///   The instantiated type instance.
   static instantiateType(_type) {
     let type = _type;
     if (!type)
@@ -77,6 +151,28 @@ class Type {
     return true;
   }
 
+  /// This method is used to create the "shortcut" types
+  /// for Mythix ORM. For example, a "string" type can be
+  /// created either via `new Types.StringType()`, or via `Types.STRING()`.
+  /// Both are equivalent. `Types.STRING` was created by calling
+  /// `Types.STRING = Type.wrapConstructor(Types.StringType)`.
+  ///
+  /// This method "wraps" a type constructor, providing a more
+  /// convenient way to create and use field types. It works
+  /// by wrapping the provided class's constructor in a callable
+  /// method. If the method **is not** called (i.e. `type: Types.STRING`)
+  /// then the type system still knows what to do, because the wrapping
+  /// method will be called by Mythix ORM to instantiate the type
+  /// when the model's fields are first fetched.
+  ///
+  /// Arguments:
+  ///   TypeKlass: class <see>Type</see>
+  ///     A `Type` class to wrap.
+  ///
+  /// Return: Function
+  ///   A callable function to instantiate the type class. If not called
+  ///   by the user, then Mythix ORM will call the method when the type
+  ///   is being created to fetch the type instance.
   static wrapConstructor(TypeKlass) {
     let TypeWrapper = function(...args) {
       return new TypeKlass(...args);
@@ -116,6 +212,15 @@ class Type {
     return TypeWrapper;
   }
 
+  /// Instantiate a new field Type.
+  ///
+  /// Arguments:
+  ///   ...args: Array<any>
+  ///     All field types "record" their constructor arguments, always.
+  ///     Mythix ORM requires that all field types, when calling `super` in
+  ///     their constructor, provide the base `Type` class all arguments
+  ///     provided to their constructor.
+  ///     This is so that the field type can later be cloned or serialized.
   constructor(...args) {
     Object.defineProperties(this, {
       '_args': {
@@ -139,6 +244,10 @@ class Type {
     });
   }
 
+  /// Clone this field type.
+  ///
+  /// Return: Type
+  ///   This field type, cloned to a new instance.
   clone() {
     let Type        = this.constructor;
     let newInstance = new Type(...this._args);
@@ -149,22 +258,86 @@ class Type {
     return newInstance;
   }
 
+  /// Check if this field type is a virtual field type.
+  ///
+  /// Note:
+  ///   This method is also a static method on the type class.
+  ///
+  /// Return: boolean
+  ///   Return `true` if this field type is a virtual field
+  ///   type. Virtual fields are fields that don't *directly*
+  ///   store a concrete value themselves. They often pull
+  ///   and combine values from other fields, or other models.
+  ///   Currently the only virtual fields in Mythix ORM are
+  ///   <see>ModelType</see> and <see>ModelsType</see>.
   isVirtual() {
     return this.constructor.isVirtual.call(this.constructor);
   }
 
+  /// Check if this field type is a relational field type.
+  ///
+  /// Note:
+  ///   This method is also a static method on the type class.
+  ///
+  /// Return: boolean
+  ///   Return `true` if this field type defines a relation,
+  ///   instead of a direct value. Field types such as
+  ///   <see>ModelType</see> and <see>ModelsType</see> are
+  ///   examples of relational field types. <see>ForeignKeyType</see>
+  ///   **is not** a relational type, but is instead considered
+  ///   a "concrete" type. Even though it does technically define
+  ///   a relationship, it is also a direct field, that actually
+  ///   has a concrete value, backed by database storage.
   isRelational() {
     return this.constructor.isRelational.call(this.constructor);
   }
 
+  /// Check if this field type is a foreign key type.
+  ///
+  /// Note:
+  ///   This method is also a static method on the type class.
+  ///
+  /// Return: boolean
+  ///   Return `true` if this field type defines a foreign key,
+  ///   or `false` otherwise.
   isForeignKey() {
     return this.constructor.isForeignKey.call(this.constructor);
   }
 
+  /// Used to decide if a field should be exposed on the model
+  /// or not.
+  ///
+  /// Some fields, such as types like <see>ModelType</see> and
+  /// <see>ModelsType</see> do not expose themselves on the model
+  /// as model fields. Instead they only expose themselves via the
+  /// relationship methods they inject onto the model instance.
+  /// Most fields **do** expose themselves on the model, but any
+  /// field that overrides this method and returns `false` will
+  /// not be exposed on the model instance.
+  ///
+  /// Note:
+  ///   This method is also a static method on the type class.
+  ///
+  /// Return: boolean
+  ///   If `true` is returned, then the field owning this type
+  ///   will be added to the model instance, and accessible by
+  ///   the user. If `false` is returned, then the field will
+  ///   be "hidden", and not exposed to the user on model instances.
   exposeToModel() {
     return this.constructor.exposeToModel.call(this.constructor);
   }
 
+  /// Check if this field's value is driven by the database.
+  ///
+  /// For example, given an AUTOINCREMENTING id field, this
+  /// would return `true`, because the value of the field is
+  /// provided by the database itself. This can be true for
+  /// nearly any field type, but is generally only true for
+  /// auto-incrementing ids, and date/time types.
+  ///
+  /// Return: boolean
+  ///   Return `true` for any field type that has a value provided
+  ///   directly by the underlying database, or `false` otherwise.
   isRemote() {
     let field = this.getField();
     if (!field)
@@ -176,19 +349,41 @@ class Type {
     return checkDefaultValueFlags(field.defaultValue, [ 'remote' ]);
   }
 
+  /// Check if the value provided is a valid value for this field type.
+  ///
+  /// This is used to check if any value *would* be a valid value for
+  /// this type. For example, if this type happens to be a <see>BooleanType</see>,
+  /// then `isValidValue` would only return `true` if the provided `value`
+  /// was either `true` or `false`. All field types have their own custom
+  /// `isValidValue` implementation, to verify values against their type.
+  ///
+  /// Arguments:
+  ///   value: any
+  ///     Any value to check.
+  ///
+  /// Return: boolean
+  ///   Return `true` if the provided `value` is a valid value for the field
+  ///   type this was called upon, or `false` otherwise.
   // eslint-disable-next-line no-unused-vars
   isValidValue(value) {
     return true;
   }
 
+  /// Get the field that owns this type.
   getField() {
     return this._field;
   }
 
+  /// Set the field that owns this type.
+  ///
+  /// Arguments:
+  ///   field: <see>Field</see>
+  ///     The field that owns this type.
   setField(field) {
     this._field = field;
   }
 
+  /// Get the model class that owns this field type.
   getModel() {
     let Model = this._Model;
     if (!Model) {
@@ -206,6 +401,11 @@ class Type {
     return Model;
   }
 
+  /// Set the model class that this type belongs to.
+  ///
+  /// Arguments:
+  ///   Model: class <see>Model</see>
+  ///     The model class that owns this field type.
   setModel(Model) {
     this._Model = Model;
   }
@@ -258,17 +458,111 @@ class Type {
   initialize(connection, self) {
   }
 
-  isDirty() {
+  /// Check if the field value is dirty.
+  ///
+  /// This is only used by some field types, such as <see>SerializedType</see>.
+  /// It will respond with `true` if the field is dirty, or `false` if it isn't.
+  ///
+  /// Interface:
+  ///   interface CheckDirtyContext {
+  ///     value: any; // The field's current value
+  ///     field: Field; // The field that is being checked
+  ///     fieldName: string; // The fieldName of the field that is being checked
+  ///     self: Model; // The model instance the field is from
+  ///     connection: ConnectionBase; // The current connection
+  ///   }
+  ///
+  /// Arguments:
+  ///   context: CheckDirtyContext
+  ///     The context provided to the call.
+  ///
+  /// Return: boolean
+  ///  Returns `true` if the field is dirty, or `false` otherwise.
+  // eslint-disable-next-line no-unused-vars
+  isDirty(context) {
   }
 
+  /// This method is called any time a field's value is set on a model.
+  ///
+  /// It is only used by the <see>SerializedType</see> to update its internal
+  /// "dirty" cache. It can be used by any field type however to detect when
+  /// a model's field's value changes.
+  ///
+  /// Interface:
+  ///   interface SetFieldValueContext {
+  ///     value: any;
+  ///     field: Field;
+  ///     fieldName: string;
+  ///     self: Model;
+  ///   }
+  ///
+  /// Arguments:
+  ///   context: SetFieldValueContext
+  ///     The context provided to the call.
+  ///
+  /// Return: undefined
+  ///   This method returns nothing.
   onSetFieldValue() {
   }
 
-  serialize(value) {
+  /// Serialize the field's value. This is the opposite of
+  /// <see>Type.deserialize</see>.
+  ///
+  /// This is used mostly by the <see>Model.toJSON</see> method
+  /// to serialize values for JSON format. However, it is also used
+  /// in some other cases, such as formatting for <see>DateType</see>
+  /// and <see>DateTimeType</see>, and for checking dirtiness in the
+  /// <see>SerializedType</see>.
+  ///
+  /// The job of this method is to serialize the field's value for any serialize operation,
+  /// generally to JSON. If a `connection` is provided as the second argument,
+  /// then it is assumed by the field type that it is being serialized for the
+  /// database. In this case the connection generally assists with the serializing
+  /// of the value. This is used for example with <see>DateType</see>
+  /// and <see>DateTimeType</see> types, when they need to be serialized to or from
+  /// a database operation.
+  ///
+  /// Arguments:
+  ///   value: any
+  ///     The field's value to serialize.
+  ///   connection?: <see>Connection</see>
+  ///     An optional connection, which if provided will likely change
+  ///     how the value is serialized.
+  ///
+  /// Return: any | string
+  ///   Though the return value will generally be a string, it isn't required
+  ///   to be.
+  ///
+  /// See: Type.deserialize
+  // eslint-disable-next-line no-unused-vars
+  serialize(value, connection) {
     return value;
   }
 
-  deserialize(value) {
+  /// Deserialize the field's value. This is the opposite of
+  /// <see>Type.serialize</see>.
+  ///
+  /// The job of this method to serialize the field's value for any serialize operation,
+  /// generally to JSON. If a `connection` is provided as the second argument,
+  /// then it is assumed by the field type that it is being serialized for the
+  /// database. In this case the connection generally assists with the serializing
+  /// of the value. This is used for example with <see>DateType</see>
+  /// and <see>DateTimeType</see> types, when they need to be serialized to or from
+  /// a database operation.
+  ///
+  /// Arguments:
+  ///   value: any
+  ///     The field's value to deserialize.
+  ///   connection?: <see>Connection</see>
+  ///     An optional connection, which if provided will likely change
+  ///     how the value is deserialized.
+  ///
+  /// Return: any
+  ///   The deserialized value for the field.
+  ///
+  /// See: Type.serialize
+  // eslint-disable-next-line no-unused-vars
+  deserialize(value, connection) {
     return value;
   }
 

package/lib/utils/async-store.js

@@ -1,3 +1,29 @@
+///! import `var { Utils: { AsyncStore } } = require('mythix-orm');`
+///!
+///! AsyncStore utilities provide the only global
+///! used in mythix-orm. The global used here is an
+///! [AsyncLocalStorage](https://nodejs.org/docs/latest-v18.x/api/async_context.html#class-asynclocalstorage) instance used to track
+///! connections (and transactions) through asynchronous
+///! calls in the engine.
+///!
+///! The `node:async_hooks` module is imported inside a
+///! `try/catch` block, so if your Javascript engine doesn't
+///! support `AsyncLocalStorage`, this will fail, and silently
+///! fallback to running the engine with no `AsyncLocalStorage`
+///! support... which simply means that connection instances need
+///! to be manually passed around everywhere.
+///!
+///! **!WARNING!: Never set the `'connection'` key, or a string key
+///! that matches one of your model names to this `AsyncLocalStorage` context
+///! unless you know exactly what you are doing. These keys are reserved
+///! by Mythix ORM to pass connections and transactions through calls.** Any
+///! and all other custom keys are available for use, though it would be
+///! wise for you to prefix your key names, so as to avoid future name collisions
+///! that might occur due to newer versions of Mythix ORM, or name collisions with
+///! other 3rd party plugins or code that might set keys on the context as well.
+///!
+///! DocScope: AsyncStore
+
 'use strict';
 
 let globalAsyncStore = global._mythixGlobalAsyncLocalStore;
@@ -14,10 +40,33 @@ if (!globalAsyncStore) {
   }
 }
 
+/// Fetch the AsyncLocalStorage store.
+/// This calls `.getStore()` on the global
+/// `AsyncLocalStorage` instance.
+///
+/// Return: any
+///   The value from a `.getStore()` call on the global `AsyncLocalStorage` instance.
+///   This will be `undefined` if no `AsyncLocalStorage` context is in scope.
 function getContextStore() {
   return globalAsyncStore.getStore();
 }
 
+/// Get a specific value from the global `AsyncLocalStorage` context
+/// by name.
+///
+/// Arguments:
+///   key: any
+///     The name of the property to return. The `AsyncLocalStorage`
+///     context internally uses a `Map` instance, so the `key` provided
+///     can be of any type.
+///   defaultValue: any
+///     The default value to return if the key specified is not found.
+///
+/// Return:
+///   Return the property named by `key` if one is found, otherwise
+///   return the `defaultValue` that was provided. If the global `AsyncLocalStorage` context is not
+///   in scope when this is called, then the `defaultValue` will always be
+///   returned.
 function getContextValue(key, defaultValue) {
   let store = globalAsyncStore.getStore();
   while (store) {
@@ -33,19 +82,47 @@ function getContextValue(key, defaultValue) {
   return defaultValue;
 }
 
+/// Set a specific value on the global `AsyncLocalStorage` context
+/// by name. A `Map` instance is used internally, so the `key` can
+/// be of any type.
+///
+/// Note:
+///   The global `AsyncLocalStorage` context must be in scope for this method to work.
+///
+/// Arguments:
+///   key: any
+///     The key you wish to set on the global `AsyncLocalStorage` context.
+///   value: any
+///     The value you wish to set on the global `AsyncLocalStorage` context.
+///
+/// Return: undefined
+///   This method returns nothing.
 function setContextValue(key, value) {
   let store = globalAsyncStore.getStore();
   if (!store || !store.context)
     return;
 
-  return store.context.set(key, value);
+  store.context.set(key, value);
 }
 
+/// Run an asynchronous method in the global `AsyncLocalStorage` context.
+///
+/// Running a method this way will provide the method, and all calls within
+/// its scope the global `AsyncLocalStorage` context.
+///
+/// Arguments:
+///   context: Map | null
+///     The context `Map` to use for the operation.
+///   callback: Function
+///     The asynchronous method to call and provide the context to.
+///
+/// Return: any
+///   The return value from the callback.
 function runInContext(context, callback) {
   return globalAsyncStore.run(
     {
-      parent: globalAsyncStore.getStore(),
-      context,
+      parent:  globalAsyncStore.getStore(),
+      context: context || new Map(),
     },
     callback,
   );