@zthun/helpful-fn 2.3.0 → 3.0.0

package/README.md

@@ -0,0 +1,14 @@
+# Helpful Functions
+
+Provides a basic set of javascript functions and classes that are not a part of the javascript engine or lodash.
+
+Helpful Functions can be used in node as well as browsers.
+
+## Installation
+
+```sh
+# NPM
+npm install @zthun/helpful-fn
+# Yarn
+yarn add @zthun/helpful-fn
+```

package/dist/lib/index.esm.js

@@ -1,2 +1,2 @@
-import{v4 as n}from"uuid";var r,t;function i(n,r,t,i){if(void 0===t&&(t=0),void 0===i&&(i=Infinity),n=Math.max(0,n),r=Math.max(0,r),Number.isNaN(n)||Number.isNaN(r))return NaN;if(0===r)return t;var e=Infinity===n?1:Math.ceil(r/n);return Math.min(i,Math.max(t,e))}function e(n,r){if(void 0===r&&(r=["message","error","exception","data"]),n instanceof Error)return n;if(null==n)return new Error;for(var t=0;t<r.length;++t){var i=r[t];if(Object.prototype.hasOwnProperty.call(n,i))return e(n[i])}return new Error(String(n))}!function(n){n.Top="top",n.Middle="middle",n.Bottom="bottom"}(r||(r={})),function(n){n.Left="left",n.Center="center",n.Right="right"}(t||(t={}));var o=n;function u(n,r){var t=[].slice.call(arguments,2);if(null!=r)return r;for(var i=0;i<t.length;++i){var e=t[i];if(null!=e)return e}return n}function l(n){return[].slice.call(arguments,1).map(function(n){return n instanceof Array?n[1]?n[0]:null:n}).filter(function(n){return null!=n}).join(n)}var a,f=l.bind(null," "),c=f,d=l.bind(null,","),v=l.bind(null,";"),m=l.bind(null,"|");function h(n,r,t){n(null!=t&&t.length?t[0]:r)}function s(n,r){return void 0===n&&(n=0),void 0===r&&(r=void 0),new Promise(function(t){return setTimeout(function(){return t(r)},n)})}!function(n){n.Horizontal="horizontal",n.Vertical="vertical"}(a||(a={}));export{t as ZHorizontalAnchor,a as ZOrientation,r as ZVerticalAnchor,d as commaJoinDefined,i as countBuckets,e as createError,o as createGuid,c as cssJoinDefined,u as firstDefined,l as joinDefined,m as pipeJoinDefined,v as semiColonJoinDefined,h as setFirst,s as sleep,f as spaceJoinDefined};
+import{v4 as n}from"uuid";var r,t;!function(n){n.Top="top",n.Middle="middle",n.Bottom="bottom"}(r||(r={})),function(n){n.Left="left",n.Center="center",n.Right="right"}(t||(t={}));var e=/*#__PURE__*/function(){function n(){this._messages=[]}n.claim=function(r,t){return(new n).claim(r,t)};var r=n.prototype;return r.claim=function(n,r){return n||this._messages.push(r),this},r.assert=function(n){if(1===this._messages.length)throw n(this._messages[0]);if(this._messages.length)throw n(this._messages)},n}();function i(n,r,t,e){if(void 0===t&&(t=0),void 0===e&&(e=Infinity),n=Math.max(0,n),r=Math.max(0,r),Number.isNaN(n)||Number.isNaN(r))return NaN;if(0===r)return t;var i=Infinity===n?1:Math.ceil(r/n);return Math.min(e,Math.max(t,i))}function o(n,r){if(void 0===r&&(r=["message","error","exception","data"]),n instanceof Error)return n;if(null==n)return new Error;for(var t=0;t<r.length;++t){var e=r[t];if(Object.prototype.hasOwnProperty.call(n,e))return o(n[e])}return new Error(String(n))}var u=n;function l(n,r){var t=[].slice.call(arguments,2);if(null!=r)return r;for(var e=0;e<t.length;++e){var i=t[e];if(null!=i)return i}return n}function a(n){return[].slice.call(arguments,1).map(function(n){return n instanceof Array?n[1]?n[0]:null:n}).filter(function(n){return null!=n}).join(n)}var s,c=a.bind(null," "),f=c,h=a.bind(null,","),m=a.bind(null,";"),v=a.bind(null,"|"),d=function(n,r){return void 0===r&&(r=null),Promise.resolve(null==n?r:function(t,e){try{var i=Promise.resolve(n).then(function(n){return null==n?r:n})}catch(n){return e()}return i&&i.then?i.then(void 0,e):i}(0,function(){return r}))},g=function(n){try{if(null==n)throw new Error("A required value was not provided");return Promise.resolve(n).then(function(n){if(null==n)throw new Error("A required value was not provided");return n})}catch(n){return Promise.reject(n)}};function p(n,r,t){n(null!=t&&t.length?t[0]:r)}function w(n,r){return void 0===n&&(n=0),void 0===r&&(r=void 0),new Promise(function(t){return setTimeout(function(){return t(r)},n)})}!function(n){n.Horizontal="horizontal",n.Vertical="vertical"}(s||(s={}));export{e as ZAssert,t as ZHorizontalAnchor,s as ZOrientation,r as ZVerticalAnchor,h as commaJoinDefined,i as countBuckets,o as createError,u as createGuid,f as cssJoinDefined,l as firstDefined,a as joinDefined,d as optional,v as pipeJoinDefined,g as required,m as semiColonJoinDefined,p as setFirst,w as sleep,c as spaceJoinDefined};
 //# sourceMappingURL=index.esm.js.map

package/dist/lib/index.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.esm.js","sources":["../../src/anchor/anchor.ts","../../src/count-buckets/count-buckets.ts","../../src/create-error/create-error.ts","../../src/create-guid/create-guid.ts","../../src/first-defined/first-defined.ts","../../src/join-defined/join-defined.ts","../../src/orientation/orientation.ts","../../src/set-first/set-first.ts","../../src/sleep/sleep.ts"],"sourcesContent":["/**\n * Represents a vertical anchor.\n */\nexport enum ZVerticalAnchor {\n  /**\n   * Top boundary.\n   */\n  Top = 'top',\n  /**\n   * Centerpoint between the top and bottom.\n   */\n  Middle = 'middle',\n  /**\n   * Bottom boundary.\n   */\n  Bottom = 'bottom'\n}\n\nexport enum ZHorizontalAnchor {\n  /**\n   * Left boundary.\n   */\n  Left = 'left',\n  /**\n   * Centerpoint between the left and right boundary.\n   */\n  Center = 'center',\n  /**\n   * Right boundary.\n   */\n  Right = 'right'\n}\n\n/**\n * Represents an anchor point.\n *\n * An anchor point is a point that stays constant while things are\n * resizing.\n */\nexport type ZAnchor = [ZVerticalAnchor, ZHorizontalAnchor];\n\n/**\n * Represents a special type of anchor that excludes the center points.\n */\nexport type ZSideAnchor =\n  | ZVerticalAnchor.Top\n  | ZVerticalAnchor.Bottom\n  | ZHorizontalAnchor.Left\n  | ZHorizontalAnchor.Right;\n","/**\n * Calculates the total number of buckets you need to\n * store a number of items where each bucket can hold a\n * maximum weight of items.\n *\n * You can use this function to calculate groupings of\n * items based on total counts and sizes.  A good example\n * usage would be to calculate the total number of pages\n * on a paginated list of items given a page size and item\n * count.\n *\n * @param weight -\n *        The maximum weight a bucket can store.\n * @param items -\n *        The total number of items you need to store where each item\n *        counts as 1 towards the weight.\n * @param min -\n *        The bounded minimum value.  If the total number of buckets\n *        evaluates to less than this value, then this value is returned.\n * @param max -\n *        The bounded maximum value.  If the total number of buckets\n *        evaluates to more than this value, then this value is returned.\n *\n * @returns\n *        The number of buckets you need to store the total number\n *        of items given that a single bucket can hold a max weight of items.\n *        If either weight or items is NaN, then NaN will be returned regardless\n *        of the opposite value.  Passing a negative number is the same as\n *        passing 0.\n */\nexport function countBuckets(weight: number, items: number, min = 0, max = Infinity) {\n  weight = Math.max(0, weight);\n  items = Math.max(0, items);\n\n  if (Number.isNaN(weight) || Number.isNaN(items)) {\n    return NaN;\n  }\n\n  if (items === 0) {\n    return min;\n  }\n\n  const boxes = weight === Infinity ? 1 : Math.ceil(items / weight);\n  return Math.min(max, Math.max(min, boxes));\n}\n","/**\n * A helper method to construct a JavaScript error object given a list of acceptable schema keys.\n *\n * @param problem -\n *        A generic representation of the problem that occurred.  This can be an Error object,\n *        another object representing some kind of error, or some message representing the error.\n *        If this is null or undefined, then a generic error is returned.\n * @param schema -\n *        The list of acceptable object keys to look into problem.  These will be recursively\n *        evaluated to strip out the real error message.  Note that this is in order of\n *        priority.  If schema[0] and schema[1] are both keys on problem, then schema[0] takes\n *        a higher precedence than schema[1].\n *\n * @returns\n *        An error object that is the best evaluation of what the problem actually is.\n */\nexport function createError(problem: any, schema = ['message', 'error', 'exception', 'data']): Error {\n  if (problem instanceof Error) {\n    return problem;\n  }\n\n  if (problem == null) {\n    return new Error();\n  }\n\n  for (let i = 0; i < schema.length; ++i) {\n    const key = schema[i];\n\n    if (Object.prototype.hasOwnProperty.call(problem, key)) {\n      return createError(problem[key]);\n    }\n  }\n\n  return new Error(String(problem));\n}\n","import { v4 } from 'uuid';\n\n/**\n * Creates a globally unique identifier.\n *\n * @returns\n *        A new generated globally unique identifier.\n */\nexport const createGuid: () => string = v4;\n","/**\n * Returns the first value in args such that args is not null or undefined.\n *\n * @param fallback -\n *        The fallback value in the case that all values in args are null/undefined.\n * @param first -\n *        The first value to check.\n * @param remaining -\n *        The remaining values beyond the first to check.\n *\n * @returns\n *        The first value if it is not null or undefined.  If first is undefined or null, then the first item\n *        in remaining such that remaining[i] is not null or undefined is returned.  If first and all values of\n *        remaining are null or undefined, then fallback is returned.\n */\nexport function firstDefined<T = any>(\n  fallback: T,\n  first: T | null | undefined,\n  ...remaining: (T | null | undefined)[]\n): T {\n  if (first != null) {\n    return first;\n  }\n\n  for (let i = 0; i < remaining.length; ++i) {\n    const val = remaining[i];\n\n    if (val != null) {\n      return val;\n    }\n  }\n\n  return fallback;\n}\n","export type JoinListInputParameter<T> = T | [T, boolean] | null | undefined;\n\n/**\n * Similar to a string join, but filters out null and undefined items.\n *\n * @param delimiter -\n *        The delimiter that separates the items.\n * @param items -\n *        The items to join.\n *\n * @returns\n *        A string that joins the items that are defined, separated by delimiter.\n */\nexport function joinDefined<T>(delimiter: string, ...items: JoinListInputParameter<T>[]) {\n  return items\n    .map((item) => (item instanceof Array ? (item[1] ? item[0] : null) : item))\n    .filter((item) => item != null)\n    .join(delimiter);\n}\n\n/**\n * Alias to joinList with a string delimiter.\n *\n * @param items -\n *        The items to join.\n *\n * @returns\n *        A string that joins the items that are defined, separated by space delimiter.\n */\nexport const spaceJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string = joinDefined.bind(null, ' ');\n\n/**\n * Alias of spaceJoinList.\n *\n * @param items -\n *        The items to join.\n *\n * @returns\n *        A string that joins the items that are defined, separated by a space delimiter.\n */\nexport const cssJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string = spaceJoinDefined;\n\n/**\n * Alias of joinList with a comma delimiter.\n *\n * @param items -\n *        The items to join.\n *\n * @returns\n *        A string that joins the items that are defined, separated by a comma delimiter.\n */\nexport const commaJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string = joinDefined.bind(null, ',');\n\n/**\n * Alias of joinList with a semi-colon delimiter.\n *\n * @param items -\n *        The items to join.\n *\n * @returns\n *        A string that joins the items that are defined, separated by a semi-colon delimiter.\n */\nexport const semiColonJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string = joinDefined.bind(null, ';');\n\n/**\n * Alias of joinList with a pipe delimiter.\n *\n * @param items -\n *        The items to join.\n *\n * @returns\n *        A string that joins the items that are defined, separated by a pipe delimiter.\n */\nexport const pipeJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string = joinDefined.bind(null, '|');\n","/**\n * Represents a direction orientation.\n */\nexport enum ZOrientation {\n  /**\n   * Row orientation.\n   *\n   * This type of orientation is a row\n   * style orientation or flex-row orientation.\n   */\n  Horizontal = 'horizontal',\n\n  /**\n   * Vertical orientation.\n   *\n   * This type of orientation is a column\n   * style orientation or block orientation.\n   */\n  Vertical = 'vertical'\n}\n","/**\n * Represents a setter function for when you want to set a single value, but you have an array instead.\n *\n * This is useful when you want to support lists of items, but you need\n * backwards compatibility for setting a single item.\n *\n * @param setValue -\n *        The setter function that takes a single value.\n * @param fallback -\n *        The fallback value in the case that there are no values.\n * @param value -\n *        The value list to retrieve the first item from.\n */\nexport function setFirst<T>(setValue: (val: T) => any, fallback: T, value: T[] | null | undefined) {\n  const _value = value?.length ? value[0] : fallback;\n  setValue(_value);\n}\n","/**\n * Halts the current thread to invoke an event loop.\n *\n * @param ms -\n *        The total number of milliseconds to sleep.\n *\n * @returns\n *        A promise that resolves after ms milliseconds.\n */\nexport function sleep(ms?: number): Promise<void>;\n\n/**\n * Halts the current thread to invoke an event loop.\n *\n * @param ms -\n *        The total number of milliseconds to sleep.\n * @param val -\n *        The value to resolve with.\n *\n * @returns\n *        A promise that resolves after ms milliseconds.\n */\nexport function sleep<T>(ms: number, val: T): Promise<T>;\n\n/**\n * Halts the current thread to invoke an event loop.\n *\n * @param ms -\n *        The total number of milliseconds to sleep.\n *\n * @returns\n *        A promise that resolves after ms milliseconds.\n */\nexport function sleep<T>(ms = 0, val: T | undefined = undefined): Promise<T | undefined> {\n  return new Promise<T | undefined>((resolve) => setTimeout(() => resolve(val), ms));\n}\n"],"names":["ZVerticalAnchor","ZHorizontalAnchor","countBuckets","weight","items","min","max","Infinity","Math","Number","isNaN","NaN","boxes","ceil","createError","problem","schema","Error","i","length","key","Object","prototype","hasOwnProperty","call","String","createGuid","v4","firstDefined","fallback","first","remaining","slice","arguments","val","joinDefined","delimiter","map","item","Array","filter","join","ZOrientation","spaceJoinDefined","bind","cssJoinDefined","commaJoinDefined","semiColonJoinDefined","pipeJoinDefined","setFirst","setValue","value","sleep","ms","undefined","Promise","resolve","setTimeout"],"mappings":"0BAGY,IAAAA,EAeAC,ECYI,SAAAC,EAAaC,EAAgBC,EAAeC,EAASC,GAInE,QAJ6D,IAAHD,IAAAA,EAAM,QAAM,IAAHC,IAAAA,EAAMC,UACzEJ,EAASK,KAAKF,IAAI,EAAGH,GACrBC,EAAQI,KAAKF,IAAI,EAAGF,GAEhBK,OAAOC,MAAMP,IAAWM,OAAOC,MAAMN,GACvC,OAAOO,IAGT,GAAc,IAAVP,EACF,OAAOC,EAGT,IAAMO,EAAmBL,WAAXJ,EAAsB,EAAIK,KAAKK,KAAKT,EAAQD,GAC1D,OAAOK,KAAKH,IAAIC,EAAKE,KAAKF,IAAID,EAAKO,GACrC,CC5BgB,SAAAE,EAAYC,EAAcC,GACxC,QAD8C,IAANA,IAAAA,EAAS,CAAC,UAAW,QAAS,YAAa,SAC/ED,aAAmBE,MACrB,OAAOF,EAGT,GAAe,MAAXA,EACF,OAAO,IAAIE,MAGb,IAAK,IAAIC,EAAI,EAAGA,EAAIF,EAAOG,SAAUD,EAAG,CACtC,IAAME,EAAMJ,EAAOE,GAEnB,GAAIG,OAAOC,UAAUC,eAAeC,KAAKT,EAASK,GAChD,OAAON,EAAYC,EAAQK,GAE9B,CAED,OAAO,IAAIH,MAAMQ,OAAOV,GAC1B,EF/BA,SAAYf,GAIVA,EAAA,IAAA,MAIAA,EAAA,OAAA,SAIAA,EAAA,OAAA,QACD,CAbD,CAAYA,IAAAA,EAaX,KAED,SAAYC,GAIVA,EAAA,KAAA,OAIAA,EAAA,OAAA,SAIAA,EAAA,MAAA,OACD,CAbD,CAAYA,IAAAA,EAaX,CAAA,IGvBY,IAAAyB,EAA2BC,ECOxB,SAAAC,EACdC,EACAC,GACG,IAAAC,EAAmC,GAAAC,MAAAR,KAAAS,UAEtC,GAAA,GAAa,MAATH,EACF,OAAOA,EAGT,IAAK,IAAIZ,EAAI,EAAGA,EAAIa,EAAUZ,SAAUD,EAAG,CACzC,IAAMgB,EAAMH,EAAUb,GAEtB,GAAW,MAAPgB,EACF,OAAOA,CAEV,CAED,OAAOL,CACT,UCpBgBM,EAAeC,GAC7B,MAAO,GAAAJ,MAAAR,KAAAS,UACJI,GAAAA,IAAI,SAACC,GAAI,OAAMA,aAAgBC,MAASD,EAAK,GAAKA,EAAK,GAAK,KAAQA,CAAI,GACxEE,OAAO,SAACF,GAAI,OAAa,MAARA,CAAY,GAC7BG,KAAKL,EACV,CAWa,IC1BDM,ED0BCC,EAAyER,EAAYS,KAAK,KAAM,KAWhGC,EAAuEF,EAWvEG,EAAyEX,EAAYS,KAAK,KAAM,KAWhGG,EAA6EZ,EAAYS,KAAK,KAAM,KAWpGI,EAAwEb,EAAYS,KAAK,KAAM,KE5D5F,SAAAK,EAAYC,EAA2BrB,EAAasB,GAElED,EADoB,MAALC,GAAAA,EAAOhC,OAASgC,EAAM,GAAKtB,EAE5C,UCiBgBuB,EAASC,EAAQnB,GAC/B,YADyB,IAAFmB,IAAAA,EAAK,YAAGnB,IAAAA,OAAqBoB,OACzCC,QAAuB,SAACC,UAAYC,WAAW,WAAM,OAAAD,EAAQtB,EAAI,EAAEmB,EAAG,EACnF,EFhCA,SAAYX,GAOVA,EAAA,WAAA,aAQAA,EAAA,SAAA,UACD,CAhBD,CAAYA,IAAAA,EAgBX,CAAA"}
+{"version":3,"file":"index.esm.js","sources":["../../src/anchor/anchor.ts","../../src/assert/assert.ts","../../src/count-buckets/count-buckets.ts","../../src/create-error/create-error.ts","../../src/create-guid/create-guid.ts","../../src/first-defined/first-defined.ts","../../src/join-defined/join-defined.ts","../../src/orientation/orientation.ts","../../src/obligation/obligation.ts","../../src/set-first/set-first.ts","../../src/sleep/sleep.ts"],"sourcesContent":["/**\n * Represents a targeted point along a y axis.\n */\nexport enum ZVerticalAnchor {\n  /**\n   * Top boundary.\n   *\n   * In vertical device space, this would equate to y = 0.\n   */\n  Top = 'top',\n  /**\n   * Centerpoint between the top and bottom.\n   */\n  Middle = 'middle',\n  /**\n   * Bottom boundary.\n   *\n   * In vertical device space, this would equate to y = Infinity.\n   */\n  Bottom = 'bottom'\n}\n\n/**\n * Represents a targeted point along an x axis.\n */\nexport enum ZHorizontalAnchor {\n  /**\n   * Left boundary.\n   *\n   * In horizontal device space, this would equate to x = 0.\n   */\n  Left = 'left',\n  /**\n   * Centerpoint between the left and right boundary.\n   */\n  Center = 'center',\n  /**\n   * Right boundary.\n   *\n   * In horizontal device space, this would equate to x = Infinity.\n   */\n  Right = 'right'\n}\n\n/**\n * Represents an anchor point in 2d space.\n *\n * An anchor array is defined by [vertical, horizontal]\n * and is read as such.\n *\n * @example\n *\n * ```ts\n * const topCenter = [ZVerticalAnchor.Top, ZHorizontalAnchor.Center];\n * const bottomRight = [ZVerticalAnchor.Bottom, ZHorizontalAnchor.Right];\n * ```\n *\n * @see {@link ZVerticalAnchor} For more information.\n * @see {@link ZHorizontalAnchor} For more information.\n */\nexport type ZAnchor = [ZVerticalAnchor, ZHorizontalAnchor];\n\n/**\n * Represents a special type of anchor that excludes the center points.\n */\nexport type ZSideAnchor =\n  | ZVerticalAnchor.Top\n  | ZVerticalAnchor.Bottom\n  | ZHorizontalAnchor.Left\n  | ZHorizontalAnchor.Right;\n","/**\n * Represents an object that can be used to build a list of assertions.\n *\n * @example\n *\n * ```ts\n * import { ZAssert, createError } from '@zthun/helpful-fn';\n *\n * const user = readUser();\n *\n * ZAssert\n *  .claim(user.name != null, 'User name is required')\n *  .claim(user.email != null, 'User email is required')\n *  .assert((m) => createError(m));\n * ```\n */\nexport class ZAssert {\n  /**\n   * Initializes a new instance of a ZAssert with one claim.\n   *\n   * @param claim -\n   *        The claim to make.\n   * @param msg -\n   *        The message to throw if the claim is false.\n   *\n   * @returns\n   *        A new ZAssert object with an initial claim.\n   */\n  public static claim(claim: boolean, msg: any): ZAssert {\n    return new ZAssert().claim(claim, msg);\n  }\n\n  private _messages: any[] = [];\n\n  /**\n   * Initializes a new instance of this object.\n   */\n  private constructor() {}\n\n  /**\n   * Adds a claim.\n   *\n   * @param claim -\n   *        The claim predicate.\n   * @param msg -\n   *        The message to add if the claim fails.\n   *\n   * @returns This object.\n   */\n  public claim(claim: boolean, msg: any): this {\n    if (!claim) {\n      this._messages.push(msg);\n    }\n    return this;\n  }\n\n  /**\n   * Runs the assertion.\n   *\n   * @param fail -\n   *        The factory that is responsible for returning the specified error to throw.\n   */\n  public assert<E extends Error>(fail: (message: any | any[]) => E): void {\n    if (this._messages.length === 1) {\n      throw fail(this._messages[0]);\n    }\n\n    if (this._messages.length) {\n      throw fail(this._messages);\n    }\n  }\n}\n","/**\n * Calculates the total number of buckets you need to\n * store a number of items where each bucket can hold a\n * maximum weight of items.\n *\n * You can use this function to calculate groupings of\n * items based on total counts and sizes.  A good example\n * usage would be to calculate the total number of pages\n * on a paginated list of items given a page size and item\n * count.\n *\n * @param weight -\n *        The maximum weight a bucket can store.  If this value receives\n *        Infinity, then it will result in 1 or min buckets being returned,\n *        whichever is larger.  If this receives NaN, then this method will\n *        result in NaN.  Finally, if this receives a negative value, then\n *        the result will be max.\n * @param items -\n *        The total number of items you need to store where each item\n *        counts as 1 towards the weight.  If the total number of items\n *        is Infinity, then this method will result in max buckets.\n *        If this receives NaN, then this method will result in NaN. Finally,\n *        if you pass 0, or a negative number of items, then result will be min.\n * @param min -\n *        The bounded minimum value.  If the total number of buckets\n *        evaluates to less than this value, then this value is returned.\n *        The default is 0.\n * @param max -\n *        The bounded maximum value.  If the total number of buckets\n *        evaluates to more than this value, then this value is returned.\n *        The default is Infinity.\n *\n * @returns\n *        The number of buckets you need to store the total number\n *        of items given that a single bucket can hold a max weight of items.\n *        If either weight or items is NaN, then NaN will be returned regardless\n *        of the opposite value.  Passing a negative number is the same as\n *        passing 0.\n *\n * @example\n *\n * ```ts\n * // The following will return 5 for numberOfPages since you need 5 buckets\n * // to store 101 number of items where each bucket can hold a max of 25\n * // items.  The 5th page would be a page of 1 item, since 1 is the remainder.\n * const numberOfPages = countBuckets(25, 101);\n *\n * // In this case, the numberOfPages would be 1 here since our minimum buckets\n * // is 1.  By default, this would be 0.\n * const numberOfPages = countBuckets(10, 0, 1);\n *\n * // In this case, we have more items that can be held in the number of buckets\n * // available, so only 4 is returned instead of the 5.\n * const numberOfPages = countBuckets(25, 101, undefined, 4);\n * ```\n */\nexport function countBuckets(weight: number, items: number, min = 0, max = Infinity) {\n  weight = Math.max(0, weight);\n  items = Math.max(0, items);\n\n  if (Number.isNaN(weight) || Number.isNaN(items)) {\n    return NaN;\n  }\n\n  if (items === 0) {\n    return min;\n  }\n\n  const boxes = weight === Infinity ? 1 : Math.ceil(items / weight);\n  return Math.min(max, Math.max(min, boxes));\n}\n","/**\n * A helper method to construct a JavaScript error object given a list of acceptable schema keys.\n *\n * @param problem -\n *        A generic representation of the problem that occurred.  This can be an Error object,\n *        another object representing some kind of error, or some message representing the error.\n *        If this is null or undefined, then a generic error is returned.\n * @param schema -\n *        The list of acceptable object keys to look into problem.  These will be recursively\n *        evaluated to strip out the real error message.  Note that this is in order of\n *        priority.  If schema[0] and schema[1] are both keys on problem, then schema[0] takes\n *        a higher precedence than schema[1].  By default, the schema will look for properties\n *        named, message, error, exception, and data, in that order.\n *\n * @returns\n *        An error object that is the best evaluation of what the problem actually is.\n *\n * @example\n *\n * ```ts\n * // All of these result an Error with the message, 'Something went wrong'\n * const errorWithStringProblem = createError('Something went wrong');\n * const errorWithObjectProblemInSchema = createError({ error: 'Something went wrong'});\n * const errorWithCustomSchema = createError({ issue: 'Something went wrong'}, ['issue']);\n * const errorRecursive = createError({ error: { message: 'Something went wrong' }});\n *\n * // This would result in '[Object object]' as there is no way to figure out how to deconstruct this problem.\n * const errorCannotBeFound = createError({ wut: 'Something went wrong' });\n * ```\n */\nexport function createError(problem: any, schema = ['message', 'error', 'exception', 'data']): Error {\n  if (problem instanceof Error) {\n    return problem;\n  }\n\n  if (problem == null) {\n    return new Error();\n  }\n\n  for (let i = 0; i < schema.length; ++i) {\n    const key = schema[i];\n\n    if (Object.prototype.hasOwnProperty.call(problem, key)) {\n      return createError(problem[key]);\n    }\n  }\n\n  return new Error(String(problem));\n}\n","import { v4 } from 'uuid';\n\n/**\n * Creates a globally unique identifier.\n *\n * The identifier holds to v4 of the UUID specification.  A summary\n * of the specification can be found at\n * {@link https://commons.apache.org/sandbox/commons-id/uuid.html | Apache Commons UUID Documentation}.\n *\n * The official documentation of the UUID specification is under\n * {@link https://www.rfc-editor.org/info/rfc4122 | RFC 4122}\n *\n * @returns\n *        A new generated globally unique identifier based on random bytes.\n *\n * @example\n *\n * ```ts\n * // Will get a value similar to 53e33fb6-d05a-4fa9-8dc0-b78e4feaa702\n * const guidA = createGuid();\n * // Will most likely not ever be equal to guidA\n * const guidB = createGuid();\n * ```\n */\nexport const createGuid: () => string = v4;\n","/**\n * Returns the first value in args such that args is not null or undefined.\n *\n * @param fallback -\n *        The fallback value in the case that all values in args are null/undefined.\n * @param first -\n *        The first value to check.\n * @param remaining -\n *        The remaining values beyond the first to check.\n * @param T -\n *        The type of data that will be enumerated.\n *\n * @returns\n *        The first value if it is not null or undefined.  If first is undefined or null, then the first item\n *        in remaining such that remaining[i] is not null or undefined is returned.  If first and all values of\n *        remaining are null or undefined, then fallback is returned.\n *\n * @example\n *\n * ```ts\n * // 'Defined'\n * const shouldBeDefined = firstDefined('Fallback', null, undefined, 'Defined');\n * // 'Fallback'\n * const shouldBeFallback = firstDefined('Fallback', null, undefined);\n * const shouldAlsoBeFallback = firstDefined('Fallback', undefined);\n * // 'First'\n * const shouldBeFirst = firstDefined('Fallback', 'First', null, 'Third');\n * ```\n *\n */\nexport function firstDefined<T = any>(\n  fallback: T,\n  first: T | null | undefined,\n  ...remaining: (T | null | undefined)[]\n): T {\n  if (first != null) {\n    return first;\n  }\n\n  for (let i = 0; i < remaining.length; ++i) {\n    const val = remaining[i];\n\n    if (val != null) {\n      return val;\n    }\n  }\n\n  return fallback;\n}\n","/**\n * A set of parameters that can be used for a string join.\n *\n * Join lists can be a regular object, null, undefined, or a tuple where the\n * first item is the object to join, and the second item is a boolean that specifies\n * whether to include it if the value is truthy.\n *\n * @param T -\n *        The type of data to join.\n */\nexport type JoinListInputParameter<T> = T | [T, boolean] | null | undefined;\n\n/**\n * Similar to {@link Array.join}, but filters out null and undefined items.\n *\n * @param delimiter -\n *        The delimiter that separates the items.\n * @param items -\n *        The items to join.\n * @param T -\n *        The type of data to join.\n *\n * @returns\n *        A string that joins the items that are defined, separated by delimiter.\n *\n * @example\n *\n * ```ts\n * // 'a b d'\n * const joinBySpace = joinDefined(' ', 'a', 'b', ['c', false], null, undefined, ['d', true]);\n * // (Empty String)\n * const joinEmpty = joinDefined('?');\n * ```\n */\nexport function joinDefined<T>(delimiter: string, ...items: JoinListInputParameter<T>[]) {\n  return items\n    .map((item) => (item instanceof Array ? (item[1] ? item[0] : null) : item))\n    .filter((item) => item != null)\n    .join(delimiter);\n}\n\n/**\n * Alias to joinList with a space delimiter.\n *\n * @param items -\n *        The items to join.\n * @param T -\n *        The type of data to join.\n *\n * @returns\n *        A string that joins the items that are defined, separated by space delimiter.\n *\n * @see\n *        {@link joinDefined} for more information and examples.\n */\nexport const spaceJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string = joinDefined.bind(null, ' ');\n\n/**\n * Alias of spaceJoinList.\n *\n * @param items -\n *        The items to join.\n * @param T -\n *        The type of data to join.\n *\n * @returns\n *        A string that joins the items that are defined, separated by a space delimiter.\n *\n * @see\n *        {@link joinDefined} for more information and examples.\n */\nexport const cssJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string = spaceJoinDefined;\n\n/**\n * Alias of joinList with a comma delimiter.\n *\n * @param items -\n *        The items to join.\n * @param T -\n *        The type of data to join.\n *\n * @returns\n *        A string that joins the items that are defined, separated by a comma delimiter.\n *\n * @see\n *        {@link joinDefined} for more information and examples.\n */\nexport const commaJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string = joinDefined.bind(null, ',');\n\n/**\n * Alias of joinList with a semi-colon delimiter.\n *\n * @param items -\n *        The items to join.\n * @param T -\n *        The type of data to join.\n *\n * @returns\n *        A string that joins the items that are defined, separated by a semi-colon delimiter.\n *\n * @see\n *        {@link joinDefined} for more information and examples.\n */\nexport const semiColonJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string = joinDefined.bind(null, ';');\n\n/**\n * Alias of joinList with a pipe delimiter.\n *\n * @param items -\n *        The items to join.\n * @param T -\n *        The type of data to join.\n *\n * @returns\n *        A string that joins the items that are defined, separated by a pipe delimiter.\n *\n * @see\n *        {@link joinDefined} for more information and examples.\n */\nexport const pipeJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string = joinDefined.bind(null, '|');\n","/**\n * Represents a direction orientation.\n */\nexport enum ZOrientation {\n  /**\n   * Horizontal orientation.\n   *\n   * This type of orientation is a row\n   * style orientation or flex-row orientation.\n   */\n  Horizontal = 'horizontal',\n\n  /**\n   * Vertical orientation.\n   *\n   * This type of orientation is a column\n   * style orientation or block orientation.\n   */\n  Vertical = 'vertical'\n}\n","/**\n * A specific set of possible values that need to be checked for requirements.\n *\n * @param T -\n *        The type of value that is being checked.\n */\nexport type ZObligatedValue<T> = T | null | undefined | Promise<T | null | undefined>;\n\n/**\n * Requires a value to be non null.\n *\n * @param val -\n *        The value to require.  This can be a promise\n *        that can return null or undefined in addition to the\n *        value.\n * @param T -\n *        The type of value that is being checked.\n *\n * @returns\n *        This method returns val if it is not null\n *        or undefined, otherwise, an error is thrown.\n *\n * @throws\n *        An error if the value is null or undefined.\n */\nexport async function required<T>(val: ZObligatedValue<T>): Promise<T> {\n  if (val == null) {\n    throw new Error('A required value was not provided');\n  }\n\n  const _val = await val;\n\n  if (_val == null) {\n    throw new Error('A required value was not provided');\n  }\n\n  return _val;\n}\n\n/**\n * Allows a value to be null or undefined and has a fallback.\n *\n * @param val -\n *        The value to check.  This can be a promise\n *        that can return null or undefined in addition to the\n *        value.\n * @param fallback -\n *        The fallback value in the case that val is\n *        null or undefined.\n * @param T -\n *        The type of value that is being checked.\n *\n * @returns\n *        This method returns val if it is not null\n *        or undefined, otherwise, the fallback is returned.\n *        If val is a promise and rejects, then fallback is\n *        also returned.\n */\nexport function optional<T>(val: ZObligatedValue<T>, fallback: T): Promise<T>;\n\n/**\n * Allows a value to be null or undefined and has a fallback.\n *\n * @param val -\n *        The value to check.  This can be a promise\n *        that can return null or undefined in addition to the\n *        value.\n * @param T -\n *        The type of value that is being checked.\n *\n * @returns\n *        This method returns val if it is not null\n *        or undefined, otherwise, null is returned.\n *        If val is a promise and rejects, then null is\n *        also returned.\n */\nexport function optional<T>(val: ZObligatedValue<T>): Promise<T | null>;\n\n/**\n * Allows a value to be null or undefined and has a fallback.\n *\n * @param val -\n *        The value to check.  This can be a promise\n *        that can return null or undefined in addition to the\n *        value.\n * @param fallback -\n *        The fallback value in the case that val is\n *        null or undefined.\n * @param T -\n *        The type of value that is being checked.\n *\n * @returns\n *        This method returns val if it is not null\n *        or undefined, otherwise, the fallback is returned.\n *        If val is a promise and rejects, then fallback is\n *        also returned.\n */\nexport async function optional<T>(val: ZObligatedValue<T>, fallback: T | null = null): Promise<T | null> {\n  if (val == null) {\n    return fallback;\n  }\n\n  try {\n    const _val = await val;\n    return _val == null ? fallback : _val;\n  } catch {\n    return fallback;\n  }\n}\n","/**\n * Represents a setter function for when you want to set a single value,\n * but you have an array instead.\n *\n * This is useful when you want to support lists of items, but you need\n * backwards compatibility for setting a single item. This is primarily meant\n * to be use with bind to construct a new method setter that takes an array\n * and forwards it to a setter method which will accept a single value of the\n * first item in the target value.\n *\n * @param setValue -\n *        The setter function that takes a single value.  This will receive\n *        the first item of the value list.\n * @param fallback -\n *        The fallback value in the case that there are no values.\n * @param value -\n *        The value list to retrieve the first item from.\n * @param T -\n *        The type of data that the array holds.\n *\n * @example\n *\n * ```ts\n * // An example of a react component that needs a value of an array, but you only care about a single selection.\n * const [value, setValue] = useState<TypesOfPie>();\n * const _values = useMemo(() => value ? [value] : [], [value]);\n * const _setValues = setFirst.bind(null, setValue, undefined);\n *\n * return <ComponentWithMultiSelectSupport values={_values} onValuesChange={_setValues} />\n * ```\n */\nexport function setFirst<T>(setValue: (val: T) => any, fallback: T, value: T[] | null | undefined) {\n  const _value = value?.length ? value[0] : fallback;\n  setValue(_value);\n}\n","/**\n * Halts the current thread to invoke an event loop.\n *\n * @param ms -\n *        The total number of milliseconds to sleep.\n *\n * @returns\n *        A promise that resolves after ms milliseconds.\n */\nexport function sleep(ms?: number): Promise<void>;\n\n/**\n * Halts the current thread to invoke an event loop.\n *\n * @param ms -\n *        The total number of milliseconds to sleep.\n * @param val -\n *        The value to resolve with.\n * @param T -\n *        The type of value that will be resolved.\n *\n * @returns\n *        A promise that resolves with val after ms milliseconds.\n */\nexport function sleep<T>(ms: number, val: T): Promise<T>;\n\n/**\n * Halts the current thread to invoke an event loop.\n *\n * @param ms -\n *        The total number of milliseconds to sleep.\n * @param T -\n *        The type of value that will be resolved.\n *\n * @returns\n *        A promise that resolves with val after ms milliseconds.\n */\nexport function sleep<T>(ms = 0, val: T | undefined = undefined): Promise<T | undefined> {\n  return new Promise<T | undefined>((resolve) => setTimeout(() => resolve(val), ms));\n}\n"],"names":["ZVerticalAnchor","ZHorizontalAnchor","ZAssert","this","_messages","claim","msg","_proto","prototype","push","assert","fail","length","countBuckets","weight","items","min","max","Infinity","Math","Number","isNaN","NaN","boxes","ceil","createError","problem","schema","Error","i","key","Object","hasOwnProperty","call","String","createGuid","v4","firstDefined","fallback","first","remaining","slice","arguments","val","joinDefined","delimiter","map","item","Array","filter","join","ZOrientation","spaceJoinDefined","bind","cssJoinDefined","commaJoinDefined","semiColonJoinDefined","pipeJoinDefined","optional","Promise","resolve","then","_val","_catch","required","e","reject","setFirst","setValue","value","sleep","ms","undefined","setTimeout"],"mappings":"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"}

package/dist/lib/index.js

@@ -1,2 +1,2 @@
-var r,e,n=require("uuid");exports.ZVerticalAnchor=void 0,(r=exports.ZVerticalAnchor||(exports.ZVerticalAnchor={})).Top="top",r.Middle="middle",r.Bottom="bottom",exports.ZHorizontalAnchor=void 0,(e=exports.ZHorizontalAnchor||(exports.ZHorizontalAnchor={})).Left="left",e.Center="center",e.Right="right";var t=n.v4;function o(r){return[].slice.call(arguments,1).map(function(r){return r instanceof Array?r[1]?r[0]:null:r}).filter(function(r){return null!=r}).join(r)}var i,a=o.bind(null," "),l=a,u=o.bind(null,","),s=o.bind(null,";"),c=o.bind(null,"|");exports.ZOrientation=void 0,(i=exports.ZOrientation||(exports.ZOrientation={})).Horizontal="horizontal",i.Vertical="vertical",exports.commaJoinDefined=u,exports.countBuckets=function(r,e,n,t){if(void 0===n&&(n=0),void 0===t&&(t=Infinity),r=Math.max(0,r),e=Math.max(0,e),Number.isNaN(r)||Number.isNaN(e))return NaN;if(0===e)return n;var o=Infinity===r?1:Math.ceil(e/r);return Math.min(t,Math.max(n,o))},exports.createError=function r(e,n){if(void 0===n&&(n=["message","error","exception","data"]),e instanceof Error)return e;if(null==e)return new Error;for(var t=0;t<n.length;++t){var o=n[t];if(Object.prototype.hasOwnProperty.call(e,o))return r(e[o])}return new Error(String(e))},exports.createGuid=t,exports.cssJoinDefined=l,exports.firstDefined=function(r,e){var n=[].slice.call(arguments,2);if(null!=e)return e;for(var t=0;t<n.length;++t){var o=n[t];if(null!=o)return o}return r},exports.joinDefined=o,exports.pipeJoinDefined=c,exports.semiColonJoinDefined=s,exports.setFirst=function(r,e,n){r(null!=n&&n.length?n[0]:e)},exports.sleep=function(r,e){return void 0===r&&(r=0),void 0===e&&(e=void 0),new Promise(function(n){return setTimeout(function(){return n(e)},r)})},exports.spaceJoinDefined=a;
+var r,e,t=require("uuid");exports.ZVerticalAnchor=void 0,(r=exports.ZVerticalAnchor||(exports.ZVerticalAnchor={})).Top="top",r.Middle="middle",r.Bottom="bottom",exports.ZHorizontalAnchor=void 0,(e=exports.ZHorizontalAnchor||(exports.ZHorizontalAnchor={})).Left="left",e.Center="center",e.Right="right";var n=/*#__PURE__*/function(){function r(){this._messages=[]}r.claim=function(e,t){return(new r).claim(e,t)};var e=r.prototype;return e.claim=function(r,e){return r||this._messages.push(e),this},e.assert=function(r){if(1===this._messages.length)throw r(this._messages[0]);if(this._messages.length)throw r(this._messages)},r}(),o=t.v4;function i(r){return[].slice.call(arguments,1).map(function(r){return r instanceof Array?r[1]?r[0]:null:r}).filter(function(r){return null!=r}).join(r)}var s,u=i.bind(null," "),l=u,a=i.bind(null,","),c=i.bind(null,";"),f=i.bind(null,"|");exports.ZOrientation=void 0,(s=exports.ZOrientation||(exports.ZOrientation={})).Horizontal="horizontal",s.Vertical="vertical",exports.ZAssert=n,exports.commaJoinDefined=a,exports.countBuckets=function(r,e,t,n){if(void 0===t&&(t=0),void 0===n&&(n=Infinity),r=Math.max(0,r),e=Math.max(0,e),Number.isNaN(r)||Number.isNaN(e))return NaN;if(0===e)return t;var o=Infinity===r?1:Math.ceil(e/r);return Math.min(n,Math.max(t,o))},exports.createError=function r(e,t){if(void 0===t&&(t=["message","error","exception","data"]),e instanceof Error)return e;if(null==e)return new Error;for(var n=0;n<t.length;++n){var o=t[n];if(Object.prototype.hasOwnProperty.call(e,o))return r(e[o])}return new Error(String(e))},exports.createGuid=o,exports.cssJoinDefined=l,exports.firstDefined=function(r,e){var t=[].slice.call(arguments,2);if(null!=e)return e;for(var n=0;n<t.length;++n){var o=t[n];if(null!=o)return o}return r},exports.joinDefined=i,exports.optional=function(r,e){return void 0===e&&(e=null),Promise.resolve(null==r?e:function(t,n){try{var o=Promise.resolve(r).then(function(r){return null==r?e:r})}catch(r){return n()}return o&&o.then?o.then(void 0,n):o}(0,function(){return e}))},exports.pipeJoinDefined=f,exports.required=function(r){try{if(null==r)throw new Error("A required value was not provided");return Promise.resolve(r).then(function(r){if(null==r)throw new Error("A required value was not provided");return r})}catch(r){return Promise.reject(r)}},exports.semiColonJoinDefined=c,exports.setFirst=function(r,e,t){r(null!=t&&t.length?t[0]:e)},exports.sleep=function(r,e){return void 0===r&&(r=0),void 0===e&&(e=void 0),new Promise(function(t){return setTimeout(function(){return t(e)},r)})},exports.spaceJoinDefined=u;
 //# sourceMappingURL=index.js.map

package/dist/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../src/anchor/anchor.ts","../../src/create-guid/create-guid.ts","../../src/join-defined/join-defined.ts","../../src/orientation/orientation.ts","../../src/count-buckets/count-buckets.ts","../../src/create-error/create-error.ts","../../src/first-defined/first-defined.ts","../../src/set-first/set-first.ts","../../src/sleep/sleep.ts"],"sourcesContent":["/**\n * Represents a vertical anchor.\n */\nexport enum ZVerticalAnchor {\n  /**\n   * Top boundary.\n   */\n  Top = 'top',\n  /**\n   * Centerpoint between the top and bottom.\n   */\n  Middle = 'middle',\n  /**\n   * Bottom boundary.\n   */\n  Bottom = 'bottom'\n}\n\nexport enum ZHorizontalAnchor {\n  /**\n   * Left boundary.\n   */\n  Left = 'left',\n  /**\n   * Centerpoint between the left and right boundary.\n   */\n  Center = 'center',\n  /**\n   * Right boundary.\n   */\n  Right = 'right'\n}\n\n/**\n * Represents an anchor point.\n *\n * An anchor point is a point that stays constant while things are\n * resizing.\n */\nexport type ZAnchor = [ZVerticalAnchor, ZHorizontalAnchor];\n\n/**\n * Represents a special type of anchor that excludes the center points.\n */\nexport type ZSideAnchor =\n  | ZVerticalAnchor.Top\n  | ZVerticalAnchor.Bottom\n  | ZHorizontalAnchor.Left\n  | ZHorizontalAnchor.Right;\n","import { v4 } from 'uuid';\n\n/**\n * Creates a globally unique identifier.\n *\n * @returns\n *        A new generated globally unique identifier.\n */\nexport const createGuid: () => string = v4;\n","export type JoinListInputParameter<T> = T | [T, boolean] | null | undefined;\n\n/**\n * Similar to a string join, but filters out null and undefined items.\n *\n * @param delimiter -\n *        The delimiter that separates the items.\n * @param items -\n *        The items to join.\n *\n * @returns\n *        A string that joins the items that are defined, separated by delimiter.\n */\nexport function joinDefined<T>(delimiter: string, ...items: JoinListInputParameter<T>[]) {\n  return items\n    .map((item) => (item instanceof Array ? (item[1] ? item[0] : null) : item))\n    .filter((item) => item != null)\n    .join(delimiter);\n}\n\n/**\n * Alias to joinList with a string delimiter.\n *\n * @param items -\n *        The items to join.\n *\n * @returns\n *        A string that joins the items that are defined, separated by space delimiter.\n */\nexport const spaceJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string = joinDefined.bind(null, ' ');\n\n/**\n * Alias of spaceJoinList.\n *\n * @param items -\n *        The items to join.\n *\n * @returns\n *        A string that joins the items that are defined, separated by a space delimiter.\n */\nexport const cssJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string = spaceJoinDefined;\n\n/**\n * Alias of joinList with a comma delimiter.\n *\n * @param items -\n *        The items to join.\n *\n * @returns\n *        A string that joins the items that are defined, separated by a comma delimiter.\n */\nexport const commaJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string = joinDefined.bind(null, ',');\n\n/**\n * Alias of joinList with a semi-colon delimiter.\n *\n * @param items -\n *        The items to join.\n *\n * @returns\n *        A string that joins the items that are defined, separated by a semi-colon delimiter.\n */\nexport const semiColonJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string = joinDefined.bind(null, ';');\n\n/**\n * Alias of joinList with a pipe delimiter.\n *\n * @param items -\n *        The items to join.\n *\n * @returns\n *        A string that joins the items that are defined, separated by a pipe delimiter.\n */\nexport const pipeJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string = joinDefined.bind(null, '|');\n","/**\n * Represents a direction orientation.\n */\nexport enum ZOrientation {\n  /**\n   * Row orientation.\n   *\n   * This type of orientation is a row\n   * style orientation or flex-row orientation.\n   */\n  Horizontal = 'horizontal',\n\n  /**\n   * Vertical orientation.\n   *\n   * This type of orientation is a column\n   * style orientation or block orientation.\n   */\n  Vertical = 'vertical'\n}\n","/**\n * Calculates the total number of buckets you need to\n * store a number of items where each bucket can hold a\n * maximum weight of items.\n *\n * You can use this function to calculate groupings of\n * items based on total counts and sizes.  A good example\n * usage would be to calculate the total number of pages\n * on a paginated list of items given a page size and item\n * count.\n *\n * @param weight -\n *        The maximum weight a bucket can store.\n * @param items -\n *        The total number of items you need to store where each item\n *        counts as 1 towards the weight.\n * @param min -\n *        The bounded minimum value.  If the total number of buckets\n *        evaluates to less than this value, then this value is returned.\n * @param max -\n *        The bounded maximum value.  If the total number of buckets\n *        evaluates to more than this value, then this value is returned.\n *\n * @returns\n *        The number of buckets you need to store the total number\n *        of items given that a single bucket can hold a max weight of items.\n *        If either weight or items is NaN, then NaN will be returned regardless\n *        of the opposite value.  Passing a negative number is the same as\n *        passing 0.\n */\nexport function countBuckets(weight: number, items: number, min = 0, max = Infinity) {\n  weight = Math.max(0, weight);\n  items = Math.max(0, items);\n\n  if (Number.isNaN(weight) || Number.isNaN(items)) {\n    return NaN;\n  }\n\n  if (items === 0) {\n    return min;\n  }\n\n  const boxes = weight === Infinity ? 1 : Math.ceil(items / weight);\n  return Math.min(max, Math.max(min, boxes));\n}\n","/**\n * A helper method to construct a JavaScript error object given a list of acceptable schema keys.\n *\n * @param problem -\n *        A generic representation of the problem that occurred.  This can be an Error object,\n *        another object representing some kind of error, or some message representing the error.\n *        If this is null or undefined, then a generic error is returned.\n * @param schema -\n *        The list of acceptable object keys to look into problem.  These will be recursively\n *        evaluated to strip out the real error message.  Note that this is in order of\n *        priority.  If schema[0] and schema[1] are both keys on problem, then schema[0] takes\n *        a higher precedence than schema[1].\n *\n * @returns\n *        An error object that is the best evaluation of what the problem actually is.\n */\nexport function createError(problem: any, schema = ['message', 'error', 'exception', 'data']): Error {\n  if (problem instanceof Error) {\n    return problem;\n  }\n\n  if (problem == null) {\n    return new Error();\n  }\n\n  for (let i = 0; i < schema.length; ++i) {\n    const key = schema[i];\n\n    if (Object.prototype.hasOwnProperty.call(problem, key)) {\n      return createError(problem[key]);\n    }\n  }\n\n  return new Error(String(problem));\n}\n","/**\n * Returns the first value in args such that args is not null or undefined.\n *\n * @param fallback -\n *        The fallback value in the case that all values in args are null/undefined.\n * @param first -\n *        The first value to check.\n * @param remaining -\n *        The remaining values beyond the first to check.\n *\n * @returns\n *        The first value if it is not null or undefined.  If first is undefined or null, then the first item\n *        in remaining such that remaining[i] is not null or undefined is returned.  If first and all values of\n *        remaining are null or undefined, then fallback is returned.\n */\nexport function firstDefined<T = any>(\n  fallback: T,\n  first: T | null | undefined,\n  ...remaining: (T | null | undefined)[]\n): T {\n  if (first != null) {\n    return first;\n  }\n\n  for (let i = 0; i < remaining.length; ++i) {\n    const val = remaining[i];\n\n    if (val != null) {\n      return val;\n    }\n  }\n\n  return fallback;\n}\n","/**\n * Represents a setter function for when you want to set a single value, but you have an array instead.\n *\n * This is useful when you want to support lists of items, but you need\n * backwards compatibility for setting a single item.\n *\n * @param setValue -\n *        The setter function that takes a single value.\n * @param fallback -\n *        The fallback value in the case that there are no values.\n * @param value -\n *        The value list to retrieve the first item from.\n */\nexport function setFirst<T>(setValue: (val: T) => any, fallback: T, value: T[] | null | undefined) {\n  const _value = value?.length ? value[0] : fallback;\n  setValue(_value);\n}\n","/**\n * Halts the current thread to invoke an event loop.\n *\n * @param ms -\n *        The total number of milliseconds to sleep.\n *\n * @returns\n *        A promise that resolves after ms milliseconds.\n */\nexport function sleep(ms?: number): Promise<void>;\n\n/**\n * Halts the current thread to invoke an event loop.\n *\n * @param ms -\n *        The total number of milliseconds to sleep.\n * @param val -\n *        The value to resolve with.\n *\n * @returns\n *        A promise that resolves after ms milliseconds.\n */\nexport function sleep<T>(ms: number, val: T): Promise<T>;\n\n/**\n * Halts the current thread to invoke an event loop.\n *\n * @param ms -\n *        The total number of milliseconds to sleep.\n *\n * @returns\n *        A promise that resolves after ms milliseconds.\n */\nexport function sleep<T>(ms = 0, val: T | undefined = undefined): Promise<T | undefined> {\n  return new Promise<T | undefined>((resolve) => setTimeout(() => resolve(val), ms));\n}\n"],"names":["ZVerticalAnchor","ZHorizontalAnchor","createGuid","v4","joinDefined","delimiter","slice","call","arguments","map","item","Array","filter","join","ZOrientation","spaceJoinDefined","bind","cssJoinDefined","commaJoinDefined","semiColonJoinDefined","pipeJoinDefined","weight","items","min","max","Infinity","Math","Number","isNaN","NaN","boxes","ceil","createError","problem","schema","Error","i","length","key","Object","prototype","hasOwnProperty","String","fallback","first","remaining","val","setValue","value","ms","undefined","Promise","resolve","setTimeout"],"mappings":"IAGYA,EAeAC,oBAfAD,QAAAA,qBAAAA,GAAAA,EAAAA,QAAeA,kBAAfA,QAAeA,gBAa1B,KATC,IAAA,MAIAA,EAAA,OAAA,SAIAA,EAAA,OAAA,SAGUC,QAAAA,uBAAAA,GAAAA,EAAAA,4BAAAA,QAAAA,kBAaX,CAAA,IATC,KAAA,OAIAA,EAAA,OAAA,SAIAA,EAAA,MAAA,QCtBW,IAAAC,EAA2BC,EAAAA,YCKxBC,EAAeC,GAC7B,MAAO,GAAAC,MAAAC,KAAAC,UACJC,GAAAA,IAAI,SAACC,GAAI,OAAMA,aAAgBC,MAASD,EAAK,GAAKA,EAAK,GAAK,KAAQA,CAAI,GACxEE,OAAO,SAACF,GAAI,OAAa,MAARA,CAAY,GAC7BG,KAAKR,EACV,CAWa,IC1BDS,ED0BCC,EAAyEX,EAAYY,KAAK,KAAM,KAWhGC,EAAuEF,EAWvEG,EAAyEd,EAAYY,KAAK,KAAM,KAWhGG,EAA6Ef,EAAYY,KAAK,KAAM,KAWpGI,EAAwEhB,EAAYY,KAAK,KAAM,KCtEhGF,QAAZA,kBAAA,GAAYA,EAAAA,QAAYA,eAAZA,QAAYA,aAgBvB,CAAA,IATC,WAAA,aAQAA,EAAA,SAAA,2DCYc,SAAaO,EAAgBC,EAAeC,EAASC,GAInE,QAJ6D,IAAHD,IAAAA,EAAM,QAAM,IAAHC,IAAAA,EAAMC,UACzEJ,EAASK,KAAKF,IAAI,EAAGH,GACrBC,EAAQI,KAAKF,IAAI,EAAGF,GAEhBK,OAAOC,MAAMP,IAAWM,OAAOC,MAAMN,GACvC,OAAOO,IAGT,GAAc,IAAVP,EACF,OAAOC,EAGT,IAAMO,EAAmBL,WAAXJ,EAAsB,EAAIK,KAAKK,KAAKT,EAAQD,GAC1D,OAAOK,KAAKH,IAAIC,EAAKE,KAAKF,IAAID,EAAKO,GACrC,sBC5BgB,SAAAE,EAAYC,EAAcC,GACxC,QAD8C,IAANA,IAAAA,EAAS,CAAC,UAAW,QAAS,YAAa,SAC/ED,aAAmBE,MACrB,OAAOF,EAGT,GAAe,MAAXA,EACF,OAAO,IAAIE,MAGb,IAAK,IAAIC,EAAI,EAAGA,EAAIF,EAAOG,SAAUD,EAAG,CACtC,IAAME,EAAMJ,EAAOE,GAEnB,GAAIG,OAAOC,UAAUC,eAAelC,KAAK0B,EAASK,GAChD,OAAON,EAAYC,EAAQK,GAE9B,CAED,OAAO,IAAIH,MAAMO,OAAOT,GAC1B,qECnBgB,SACdU,EACAC,GACG,IAAAC,EAAmC,GAAAvC,MAAAC,KAAAC,UAEtC,GAAA,GAAa,MAAToC,EACF,OAAOA,EAGT,IAAK,IAAIR,EAAI,EAAGA,EAAIS,EAAUR,SAAUD,EAAG,CACzC,IAAMU,EAAMD,EAAUT,GAEtB,GAAW,MAAPU,EACF,OAAOA,CAEV,CAED,OAAOH,CACT,kGCpBgB,SAAYI,EAA2BJ,EAAaK,GAElED,EADoB,MAALC,GAAAA,EAAOX,OAASW,EAAM,GAAKL,EAE5C,yBCiByBM,EAAQH,GAC/B,YADyB,IAAFG,IAAAA,EAAK,YAAGH,IAAAA,OAAqBI,OACzCC,QAAuB,SAACC,UAAYC,WAAW,WAAM,OAAAD,EAAQN,EAAI,EAAEG,EAAG,EACnF"}
+{"version":3,"file":"index.js","sources":["../../src/anchor/anchor.ts","../../src/assert/assert.ts","../../src/create-guid/create-guid.ts","../../src/join-defined/join-defined.ts","../../src/orientation/orientation.ts","../../src/count-buckets/count-buckets.ts","../../src/create-error/create-error.ts","../../src/first-defined/first-defined.ts","../../src/obligation/obligation.ts","../../src/set-first/set-first.ts","../../src/sleep/sleep.ts"],"sourcesContent":["/**\n * Represents a targeted point along a y axis.\n */\nexport enum ZVerticalAnchor {\n  /**\n   * Top boundary.\n   *\n   * In vertical device space, this would equate to y = 0.\n   */\n  Top = 'top',\n  /**\n   * Centerpoint between the top and bottom.\n   */\n  Middle = 'middle',\n  /**\n   * Bottom boundary.\n   *\n   * In vertical device space, this would equate to y = Infinity.\n   */\n  Bottom = 'bottom'\n}\n\n/**\n * Represents a targeted point along an x axis.\n */\nexport enum ZHorizontalAnchor {\n  /**\n   * Left boundary.\n   *\n   * In horizontal device space, this would equate to x = 0.\n   */\n  Left = 'left',\n  /**\n   * Centerpoint between the left and right boundary.\n   */\n  Center = 'center',\n  /**\n   * Right boundary.\n   *\n   * In horizontal device space, this would equate to x = Infinity.\n   */\n  Right = 'right'\n}\n\n/**\n * Represents an anchor point in 2d space.\n *\n * An anchor array is defined by [vertical, horizontal]\n * and is read as such.\n *\n * @example\n *\n * ```ts\n * const topCenter = [ZVerticalAnchor.Top, ZHorizontalAnchor.Center];\n * const bottomRight = [ZVerticalAnchor.Bottom, ZHorizontalAnchor.Right];\n * ```\n *\n * @see {@link ZVerticalAnchor} For more information.\n * @see {@link ZHorizontalAnchor} For more information.\n */\nexport type ZAnchor = [ZVerticalAnchor, ZHorizontalAnchor];\n\n/**\n * Represents a special type of anchor that excludes the center points.\n */\nexport type ZSideAnchor =\n  | ZVerticalAnchor.Top\n  | ZVerticalAnchor.Bottom\n  | ZHorizontalAnchor.Left\n  | ZHorizontalAnchor.Right;\n","/**\n * Represents an object that can be used to build a list of assertions.\n *\n * @example\n *\n * ```ts\n * import { ZAssert, createError } from '@zthun/helpful-fn';\n *\n * const user = readUser();\n *\n * ZAssert\n *  .claim(user.name != null, 'User name is required')\n *  .claim(user.email != null, 'User email is required')\n *  .assert((m) => createError(m));\n * ```\n */\nexport class ZAssert {\n  /**\n   * Initializes a new instance of a ZAssert with one claim.\n   *\n   * @param claim -\n   *        The claim to make.\n   * @param msg -\n   *        The message to throw if the claim is false.\n   *\n   * @returns\n   *        A new ZAssert object with an initial claim.\n   */\n  public static claim(claim: boolean, msg: any): ZAssert {\n    return new ZAssert().claim(claim, msg);\n  }\n\n  private _messages: any[] = [];\n\n  /**\n   * Initializes a new instance of this object.\n   */\n  private constructor() {}\n\n  /**\n   * Adds a claim.\n   *\n   * @param claim -\n   *        The claim predicate.\n   * @param msg -\n   *        The message to add if the claim fails.\n   *\n   * @returns This object.\n   */\n  public claim(claim: boolean, msg: any): this {\n    if (!claim) {\n      this._messages.push(msg);\n    }\n    return this;\n  }\n\n  /**\n   * Runs the assertion.\n   *\n   * @param fail -\n   *        The factory that is responsible for returning the specified error to throw.\n   */\n  public assert<E extends Error>(fail: (message: any | any[]) => E): void {\n    if (this._messages.length === 1) {\n      throw fail(this._messages[0]);\n    }\n\n    if (this._messages.length) {\n      throw fail(this._messages);\n    }\n  }\n}\n","import { v4 } from 'uuid';\n\n/**\n * Creates a globally unique identifier.\n *\n * The identifier holds to v4 of the UUID specification.  A summary\n * of the specification can be found at\n * {@link https://commons.apache.org/sandbox/commons-id/uuid.html | Apache Commons UUID Documentation}.\n *\n * The official documentation of the UUID specification is under\n * {@link https://www.rfc-editor.org/info/rfc4122 | RFC 4122}\n *\n * @returns\n *        A new generated globally unique identifier based on random bytes.\n *\n * @example\n *\n * ```ts\n * // Will get a value similar to 53e33fb6-d05a-4fa9-8dc0-b78e4feaa702\n * const guidA = createGuid();\n * // Will most likely not ever be equal to guidA\n * const guidB = createGuid();\n * ```\n */\nexport const createGuid: () => string = v4;\n","/**\n * A set of parameters that can be used for a string join.\n *\n * Join lists can be a regular object, null, undefined, or a tuple where the\n * first item is the object to join, and the second item is a boolean that specifies\n * whether to include it if the value is truthy.\n *\n * @param T -\n *        The type of data to join.\n */\nexport type JoinListInputParameter<T> = T | [T, boolean] | null | undefined;\n\n/**\n * Similar to {@link Array.join}, but filters out null and undefined items.\n *\n * @param delimiter -\n *        The delimiter that separates the items.\n * @param items -\n *        The items to join.\n * @param T -\n *        The type of data to join.\n *\n * @returns\n *        A string that joins the items that are defined, separated by delimiter.\n *\n * @example\n *\n * ```ts\n * // 'a b d'\n * const joinBySpace = joinDefined(' ', 'a', 'b', ['c', false], null, undefined, ['d', true]);\n * // (Empty String)\n * const joinEmpty = joinDefined('?');\n * ```\n */\nexport function joinDefined<T>(delimiter: string, ...items: JoinListInputParameter<T>[]) {\n  return items\n    .map((item) => (item instanceof Array ? (item[1] ? item[0] : null) : item))\n    .filter((item) => item != null)\n    .join(delimiter);\n}\n\n/**\n * Alias to joinList with a space delimiter.\n *\n * @param items -\n *        The items to join.\n * @param T -\n *        The type of data to join.\n *\n * @returns\n *        A string that joins the items that are defined, separated by space delimiter.\n *\n * @see\n *        {@link joinDefined} for more information and examples.\n */\nexport const spaceJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string = joinDefined.bind(null, ' ');\n\n/**\n * Alias of spaceJoinList.\n *\n * @param items -\n *        The items to join.\n * @param T -\n *        The type of data to join.\n *\n * @returns\n *        A string that joins the items that are defined, separated by a space delimiter.\n *\n * @see\n *        {@link joinDefined} for more information and examples.\n */\nexport const cssJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string = spaceJoinDefined;\n\n/**\n * Alias of joinList with a comma delimiter.\n *\n * @param items -\n *        The items to join.\n * @param T -\n *        The type of data to join.\n *\n * @returns\n *        A string that joins the items that are defined, separated by a comma delimiter.\n *\n * @see\n *        {@link joinDefined} for more information and examples.\n */\nexport const commaJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string = joinDefined.bind(null, ',');\n\n/**\n * Alias of joinList with a semi-colon delimiter.\n *\n * @param items -\n *        The items to join.\n * @param T -\n *        The type of data to join.\n *\n * @returns\n *        A string that joins the items that are defined, separated by a semi-colon delimiter.\n *\n * @see\n *        {@link joinDefined} for more information and examples.\n */\nexport const semiColonJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string = joinDefined.bind(null, ';');\n\n/**\n * Alias of joinList with a pipe delimiter.\n *\n * @param items -\n *        The items to join.\n * @param T -\n *        The type of data to join.\n *\n * @returns\n *        A string that joins the items that are defined, separated by a pipe delimiter.\n *\n * @see\n *        {@link joinDefined} for more information and examples.\n */\nexport const pipeJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string = joinDefined.bind(null, '|');\n","/**\n * Represents a direction orientation.\n */\nexport enum ZOrientation {\n  /**\n   * Horizontal orientation.\n   *\n   * This type of orientation is a row\n   * style orientation or flex-row orientation.\n   */\n  Horizontal = 'horizontal',\n\n  /**\n   * Vertical orientation.\n   *\n   * This type of orientation is a column\n   * style orientation or block orientation.\n   */\n  Vertical = 'vertical'\n}\n","/**\n * Calculates the total number of buckets you need to\n * store a number of items where each bucket can hold a\n * maximum weight of items.\n *\n * You can use this function to calculate groupings of\n * items based on total counts and sizes.  A good example\n * usage would be to calculate the total number of pages\n * on a paginated list of items given a page size and item\n * count.\n *\n * @param weight -\n *        The maximum weight a bucket can store.  If this value receives\n *        Infinity, then it will result in 1 or min buckets being returned,\n *        whichever is larger.  If this receives NaN, then this method will\n *        result in NaN.  Finally, if this receives a negative value, then\n *        the result will be max.\n * @param items -\n *        The total number of items you need to store where each item\n *        counts as 1 towards the weight.  If the total number of items\n *        is Infinity, then this method will result in max buckets.\n *        If this receives NaN, then this method will result in NaN. Finally,\n *        if you pass 0, or a negative number of items, then result will be min.\n * @param min -\n *        The bounded minimum value.  If the total number of buckets\n *        evaluates to less than this value, then this value is returned.\n *        The default is 0.\n * @param max -\n *        The bounded maximum value.  If the total number of buckets\n *        evaluates to more than this value, then this value is returned.\n *        The default is Infinity.\n *\n * @returns\n *        The number of buckets you need to store the total number\n *        of items given that a single bucket can hold a max weight of items.\n *        If either weight or items is NaN, then NaN will be returned regardless\n *        of the opposite value.  Passing a negative number is the same as\n *        passing 0.\n *\n * @example\n *\n * ```ts\n * // The following will return 5 for numberOfPages since you need 5 buckets\n * // to store 101 number of items where each bucket can hold a max of 25\n * // items.  The 5th page would be a page of 1 item, since 1 is the remainder.\n * const numberOfPages = countBuckets(25, 101);\n *\n * // In this case, the numberOfPages would be 1 here since our minimum buckets\n * // is 1.  By default, this would be 0.\n * const numberOfPages = countBuckets(10, 0, 1);\n *\n * // In this case, we have more items that can be held in the number of buckets\n * // available, so only 4 is returned instead of the 5.\n * const numberOfPages = countBuckets(25, 101, undefined, 4);\n * ```\n */\nexport function countBuckets(weight: number, items: number, min = 0, max = Infinity) {\n  weight = Math.max(0, weight);\n  items = Math.max(0, items);\n\n  if (Number.isNaN(weight) || Number.isNaN(items)) {\n    return NaN;\n  }\n\n  if (items === 0) {\n    return min;\n  }\n\n  const boxes = weight === Infinity ? 1 : Math.ceil(items / weight);\n  return Math.min(max, Math.max(min, boxes));\n}\n","/**\n * A helper method to construct a JavaScript error object given a list of acceptable schema keys.\n *\n * @param problem -\n *        A generic representation of the problem that occurred.  This can be an Error object,\n *        another object representing some kind of error, or some message representing the error.\n *        If this is null or undefined, then a generic error is returned.\n * @param schema -\n *        The list of acceptable object keys to look into problem.  These will be recursively\n *        evaluated to strip out the real error message.  Note that this is in order of\n *        priority.  If schema[0] and schema[1] are both keys on problem, then schema[0] takes\n *        a higher precedence than schema[1].  By default, the schema will look for properties\n *        named, message, error, exception, and data, in that order.\n *\n * @returns\n *        An error object that is the best evaluation of what the problem actually is.\n *\n * @example\n *\n * ```ts\n * // All of these result an Error with the message, 'Something went wrong'\n * const errorWithStringProblem = createError('Something went wrong');\n * const errorWithObjectProblemInSchema = createError({ error: 'Something went wrong'});\n * const errorWithCustomSchema = createError({ issue: 'Something went wrong'}, ['issue']);\n * const errorRecursive = createError({ error: { message: 'Something went wrong' }});\n *\n * // This would result in '[Object object]' as there is no way to figure out how to deconstruct this problem.\n * const errorCannotBeFound = createError({ wut: 'Something went wrong' });\n * ```\n */\nexport function createError(problem: any, schema = ['message', 'error', 'exception', 'data']): Error {\n  if (problem instanceof Error) {\n    return problem;\n  }\n\n  if (problem == null) {\n    return new Error();\n  }\n\n  for (let i = 0; i < schema.length; ++i) {\n    const key = schema[i];\n\n    if (Object.prototype.hasOwnProperty.call(problem, key)) {\n      return createError(problem[key]);\n    }\n  }\n\n  return new Error(String(problem));\n}\n","/**\n * Returns the first value in args such that args is not null or undefined.\n *\n * @param fallback -\n *        The fallback value in the case that all values in args are null/undefined.\n * @param first -\n *        The first value to check.\n * @param remaining -\n *        The remaining values beyond the first to check.\n * @param T -\n *        The type of data that will be enumerated.\n *\n * @returns\n *        The first value if it is not null or undefined.  If first is undefined or null, then the first item\n *        in remaining such that remaining[i] is not null or undefined is returned.  If first and all values of\n *        remaining are null or undefined, then fallback is returned.\n *\n * @example\n *\n * ```ts\n * // 'Defined'\n * const shouldBeDefined = firstDefined('Fallback', null, undefined, 'Defined');\n * // 'Fallback'\n * const shouldBeFallback = firstDefined('Fallback', null, undefined);\n * const shouldAlsoBeFallback = firstDefined('Fallback', undefined);\n * // 'First'\n * const shouldBeFirst = firstDefined('Fallback', 'First', null, 'Third');\n * ```\n *\n */\nexport function firstDefined<T = any>(\n  fallback: T,\n  first: T | null | undefined,\n  ...remaining: (T | null | undefined)[]\n): T {\n  if (first != null) {\n    return first;\n  }\n\n  for (let i = 0; i < remaining.length; ++i) {\n    const val = remaining[i];\n\n    if (val != null) {\n      return val;\n    }\n  }\n\n  return fallback;\n}\n","/**\n * A specific set of possible values that need to be checked for requirements.\n *\n * @param T -\n *        The type of value that is being checked.\n */\nexport type ZObligatedValue<T> = T | null | undefined | Promise<T | null | undefined>;\n\n/**\n * Requires a value to be non null.\n *\n * @param val -\n *        The value to require.  This can be a promise\n *        that can return null or undefined in addition to the\n *        value.\n * @param T -\n *        The type of value that is being checked.\n *\n * @returns\n *        This method returns val if it is not null\n *        or undefined, otherwise, an error is thrown.\n *\n * @throws\n *        An error if the value is null or undefined.\n */\nexport async function required<T>(val: ZObligatedValue<T>): Promise<T> {\n  if (val == null) {\n    throw new Error('A required value was not provided');\n  }\n\n  const _val = await val;\n\n  if (_val == null) {\n    throw new Error('A required value was not provided');\n  }\n\n  return _val;\n}\n\n/**\n * Allows a value to be null or undefined and has a fallback.\n *\n * @param val -\n *        The value to check.  This can be a promise\n *        that can return null or undefined in addition to the\n *        value.\n * @param fallback -\n *        The fallback value in the case that val is\n *        null or undefined.\n * @param T -\n *        The type of value that is being checked.\n *\n * @returns\n *        This method returns val if it is not null\n *        or undefined, otherwise, the fallback is returned.\n *        If val is a promise and rejects, then fallback is\n *        also returned.\n */\nexport function optional<T>(val: ZObligatedValue<T>, fallback: T): Promise<T>;\n\n/**\n * Allows a value to be null or undefined and has a fallback.\n *\n * @param val -\n *        The value to check.  This can be a promise\n *        that can return null or undefined in addition to the\n *        value.\n * @param T -\n *        The type of value that is being checked.\n *\n * @returns\n *        This method returns val if it is not null\n *        or undefined, otherwise, null is returned.\n *        If val is a promise and rejects, then null is\n *        also returned.\n */\nexport function optional<T>(val: ZObligatedValue<T>): Promise<T | null>;\n\n/**\n * Allows a value to be null or undefined and has a fallback.\n *\n * @param val -\n *        The value to check.  This can be a promise\n *        that can return null or undefined in addition to the\n *        value.\n * @param fallback -\n *        The fallback value in the case that val is\n *        null or undefined.\n * @param T -\n *        The type of value that is being checked.\n *\n * @returns\n *        This method returns val if it is not null\n *        or undefined, otherwise, the fallback is returned.\n *        If val is a promise and rejects, then fallback is\n *        also returned.\n */\nexport async function optional<T>(val: ZObligatedValue<T>, fallback: T | null = null): Promise<T | null> {\n  if (val == null) {\n    return fallback;\n  }\n\n  try {\n    const _val = await val;\n    return _val == null ? fallback : _val;\n  } catch {\n    return fallback;\n  }\n}\n","/**\n * Represents a setter function for when you want to set a single value,\n * but you have an array instead.\n *\n * This is useful when you want to support lists of items, but you need\n * backwards compatibility for setting a single item. This is primarily meant\n * to be use with bind to construct a new method setter that takes an array\n * and forwards it to a setter method which will accept a single value of the\n * first item in the target value.\n *\n * @param setValue -\n *        The setter function that takes a single value.  This will receive\n *        the first item of the value list.\n * @param fallback -\n *        The fallback value in the case that there are no values.\n * @param value -\n *        The value list to retrieve the first item from.\n * @param T -\n *        The type of data that the array holds.\n *\n * @example\n *\n * ```ts\n * // An example of a react component that needs a value of an array, but you only care about a single selection.\n * const [value, setValue] = useState<TypesOfPie>();\n * const _values = useMemo(() => value ? [value] : [], [value]);\n * const _setValues = setFirst.bind(null, setValue, undefined);\n *\n * return <ComponentWithMultiSelectSupport values={_values} onValuesChange={_setValues} />\n * ```\n */\nexport function setFirst<T>(setValue: (val: T) => any, fallback: T, value: T[] | null | undefined) {\n  const _value = value?.length ? value[0] : fallback;\n  setValue(_value);\n}\n","/**\n * Halts the current thread to invoke an event loop.\n *\n * @param ms -\n *        The total number of milliseconds to sleep.\n *\n * @returns\n *        A promise that resolves after ms milliseconds.\n */\nexport function sleep(ms?: number): Promise<void>;\n\n/**\n * Halts the current thread to invoke an event loop.\n *\n * @param ms -\n *        The total number of milliseconds to sleep.\n * @param val -\n *        The value to resolve with.\n * @param T -\n *        The type of value that will be resolved.\n *\n * @returns\n *        A promise that resolves with val after ms milliseconds.\n */\nexport function sleep<T>(ms: number, val: T): Promise<T>;\n\n/**\n * Halts the current thread to invoke an event loop.\n *\n * @param ms -\n *        The total number of milliseconds to sleep.\n * @param T -\n *        The type of value that will be resolved.\n *\n * @returns\n *        A promise that resolves with val after ms milliseconds.\n */\nexport function sleep<T>(ms = 0, val: T | undefined = undefined): Promise<T | undefined> {\n  return new Promise<T | undefined>((resolve) => setTimeout(() => resolve(val), ms));\n}\n"],"names":["ZVerticalAnchor","ZHorizontalAnchor","ZAssert","this","_messages","claim","msg","_proto","prototype","push","assert","fail","length","createGuid","v4","joinDefined","delimiter","slice","call","arguments","map","item","Array","filter","join","ZOrientation","spaceJoinDefined","bind","cssJoinDefined","commaJoinDefined","semiColonJoinDefined","pipeJoinDefined","weight","items","min","max","Infinity","Math","Number","isNaN","NaN","boxes","ceil","createError","problem","schema","Error","i","key","Object","hasOwnProperty","String","fallback","first","remaining","val","Promise","resolve","then","_val","_catch","e","reject","setValue","value","ms","undefined","setTimeout"],"mappings":"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"}

package/dist/types/anchor/anchor.d.ts

@@ -1,9 +1,11 @@
 /**
- * Represents a vertical anchor.
+ * Represents a targeted point along a y axis.
  */
 export declare enum ZVerticalAnchor {
     /**
      * Top boundary.
+     *
+     * In vertical device space, this would equate to y = 0.
      */
     Top = "top",
     /**
@@ -12,12 +14,19 @@ export declare enum ZVerticalAnchor {
     Middle = "middle",
     /**
      * Bottom boundary.
+     *
+     * In vertical device space, this would equate to y = Infinity.
      */
     Bottom = "bottom"
 }
+/**
+ * Represents a targeted point along an x axis.
+ */
 export declare enum ZHorizontalAnchor {
     /**
      * Left boundary.
+     *
+     * In horizontal device space, this would equate to x = 0.
      */
     Left = "left",
     /**
@@ -26,14 +35,26 @@ export declare enum ZHorizontalAnchor {
     Center = "center",
     /**
      * Right boundary.
+     *
+     * In horizontal device space, this would equate to x = Infinity.
      */
     Right = "right"
 }
 /**
- * Represents an anchor point.
+ * Represents an anchor point in 2d space.
+ *
+ * An anchor array is defined by [vertical, horizontal]
+ * and is read as such.
+ *
+ * @example
+ *
+ * ```ts
+ * const topCenter = [ZVerticalAnchor.Top, ZHorizontalAnchor.Center];
+ * const bottomRight = [ZVerticalAnchor.Bottom, ZHorizontalAnchor.Right];
+ * ```
  *
- * An anchor point is a point that stays constant while things are
- * resizing.
+ * @see {@link ZVerticalAnchor} For more information.
+ * @see {@link ZHorizontalAnchor} For more information.
  */
 export type ZAnchor = [ZVerticalAnchor, ZHorizontalAnchor];
 /**

package/dist/types/assert/assert.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Represents an object that can be used to build a list of assertions.
+ *
+ * @example
+ *
+ * ```ts
+ * import { ZAssert, createError } from '@zthun/helpful-fn';
+ *
+ * const user = readUser();
+ *
+ * ZAssert
+ *  .claim(user.name != null, 'User name is required')
+ *  .claim(user.email != null, 'User email is required')
+ *  .assert((m) => createError(m));
+ * ```
+ */
+export declare class ZAssert {
+    /**
+     * Initializes a new instance of a ZAssert with one claim.
+     *
+     * @param claim -
+     *        The claim to make.
+     * @param msg -
+     *        The message to throw if the claim is false.
+     *
+     * @returns
+     *        A new ZAssert object with an initial claim.
+     */
+    static claim(claim: boolean, msg: any): ZAssert;
+    private _messages;
+    /**
+     * Initializes a new instance of this object.
+     */
+    private constructor();
+    /**
+     * Adds a claim.
+     *
+     * @param claim -
+     *        The claim predicate.
+     * @param msg -
+     *        The message to add if the claim fails.
+     *
+     * @returns This object.
+     */
+    claim(claim: boolean, msg: any): this;
+    /**
+     * Runs the assertion.
+     *
+     * @param fail -
+     *        The factory that is responsible for returning the specified error to throw.
+     */
+    assert<E extends Error>(fail: (message: any | any[]) => E): void;
+}

package/dist/types/count-buckets/count-buckets.d.ts

@@ -10,16 +10,25 @@
  * count.
  *
  * @param weight -
- *        The maximum weight a bucket can store.
+ *        The maximum weight a bucket can store.  If this value receives
+ *        Infinity, then it will result in 1 or min buckets being returned,
+ *        whichever is larger.  If this receives NaN, then this method will
+ *        result in NaN.  Finally, if this receives a negative value, then
+ *        the result will be max.
  * @param items -
  *        The total number of items you need to store where each item
- *        counts as 1 towards the weight.
+ *        counts as 1 towards the weight.  If the total number of items
+ *        is Infinity, then this method will result in max buckets.
+ *        If this receives NaN, then this method will result in NaN. Finally,
+ *        if you pass 0, or a negative number of items, then result will be min.
  * @param min -
  *        The bounded minimum value.  If the total number of buckets
  *        evaluates to less than this value, then this value is returned.
+ *        The default is 0.
  * @param max -
  *        The bounded maximum value.  If the total number of buckets
  *        evaluates to more than this value, then this value is returned.
+ *        The default is Infinity.
  *
  * @returns
  *        The number of buckets you need to store the total number
@@ -27,5 +36,22 @@
  *        If either weight or items is NaN, then NaN will be returned regardless
  *        of the opposite value.  Passing a negative number is the same as
  *        passing 0.
+ *
+ * @example
+ *
+ * ```ts
+ * // The following will return 5 for numberOfPages since you need 5 buckets
+ * // to store 101 number of items where each bucket can hold a max of 25
+ * // items.  The 5th page would be a page of 1 item, since 1 is the remainder.
+ * const numberOfPages = countBuckets(25, 101);
+ *
+ * // In this case, the numberOfPages would be 1 here since our minimum buckets
+ * // is 1.  By default, this would be 0.
+ * const numberOfPages = countBuckets(10, 0, 1);
+ *
+ * // In this case, we have more items that can be held in the number of buckets
+ * // available, so only 4 is returned instead of the 5.
+ * const numberOfPages = countBuckets(25, 101, undefined, 4);
+ * ```
  */
 export declare function countBuckets(weight: number, items: number, min?: number, max?: number): number;

package/dist/types/create-error/create-error.d.ts

@@ -9,9 +9,23 @@
  *        The list of acceptable object keys to look into problem.  These will be recursively
  *        evaluated to strip out the real error message.  Note that this is in order of
  *        priority.  If schema[0] and schema[1] are both keys on problem, then schema[0] takes
- *        a higher precedence than schema[1].
+ *        a higher precedence than schema[1].  By default, the schema will look for properties
+ *        named, message, error, exception, and data, in that order.
  *
  * @returns
  *        An error object that is the best evaluation of what the problem actually is.
+ *
+ * @example
+ *
+ * ```ts
+ * // All of these result an Error with the message, 'Something went wrong'
+ * const errorWithStringProblem = createError('Something went wrong');
+ * const errorWithObjectProblemInSchema = createError({ error: 'Something went wrong'});
+ * const errorWithCustomSchema = createError({ issue: 'Something went wrong'}, ['issue']);
+ * const errorRecursive = createError({ error: { message: 'Something went wrong' }});
+ *
+ * // This would result in '[Object object]' as there is no way to figure out how to deconstruct this problem.
+ * const errorCannotBeFound = createError({ wut: 'Something went wrong' });
+ * ```
  */
 export declare function createError(problem: any, schema?: string[]): Error;

package/dist/types/create-guid/create-guid.d.ts

@@ -1,7 +1,23 @@
 /**
  * Creates a globally unique identifier.
  *
+ * The identifier holds to v4 of the UUID specification.  A summary
+ * of the specification can be found at
+ * {@link https://commons.apache.org/sandbox/commons-id/uuid.html | Apache Commons UUID Documentation}.
+ *
+ * The official documentation of the UUID specification is under
+ * {@link https://www.rfc-editor.org/info/rfc4122 | RFC 4122}
+ *
  * @returns
- *        A new generated globally unique identifier.
+ *        A new generated globally unique identifier based on random bytes.
+ *
+ * @example
+ *
+ * ```ts
+ * // Will get a value similar to 53e33fb6-d05a-4fa9-8dc0-b78e4feaa702
+ * const guidA = createGuid();
+ * // Will most likely not ever be equal to guidA
+ * const guidB = createGuid();
+ * ```
  */
 export declare const createGuid: () => string;

package/dist/types/first-defined/first-defined.d.ts

@@ -7,10 +7,25 @@
  *        The first value to check.
  * @param remaining -
  *        The remaining values beyond the first to check.
+ * @param T -
+ *        The type of data that will be enumerated.
  *
  * @returns
  *        The first value if it is not null or undefined.  If first is undefined or null, then the first item
  *        in remaining such that remaining[i] is not null or undefined is returned.  If first and all values of
  *        remaining are null or undefined, then fallback is returned.
+ *
+ * @example
+ *
+ * ```ts
+ * // 'Defined'
+ * const shouldBeDefined = firstDefined('Fallback', null, undefined, 'Defined');
+ * // 'Fallback'
+ * const shouldBeFallback = firstDefined('Fallback', null, undefined);
+ * const shouldAlsoBeFallback = firstDefined('Fallback', undefined);
+ * // 'First'
+ * const shouldBeFirst = firstDefined('Fallback', 'First', null, 'Third');
+ * ```
+ *
  */
 export declare function firstDefined<T = any>(fallback: T, first: T | null | undefined, ...remaining: (T | null | undefined)[]): T;

package/dist/types/index.d.ts

@@ -1,9 +1,11 @@
 export * from './anchor/anchor';
+export * from './assert/assert';
 export * from './count-buckets/count-buckets';
 export * from './create-error/create-error';
 export * from './create-guid/create-guid';
 export * from './first-defined/first-defined';
 export * from './join-defined/join-defined';
+export * from './obligation/obligation';
 export * from './orientation/orientation';
 export * from './set-first/set-first';
 export * from './sleep/sleep';

package/dist/types/join-defined/join-defined.d.ts

@@ -1,24 +1,50 @@
+/**
+ * A set of parameters that can be used for a string join.
+ *
+ * Join lists can be a regular object, null, undefined, or a tuple where the
+ * first item is the object to join, and the second item is a boolean that specifies
+ * whether to include it if the value is truthy.
+ *
+ * @param T -
+ *        The type of data to join.
+ */
 export type JoinListInputParameter<T> = T | [T, boolean] | null | undefined;
 /**
- * Similar to a string join, but filters out null and undefined items.
+ * Similar to {@link Array.join}, but filters out null and undefined items.
  *
  * @param delimiter -
  *        The delimiter that separates the items.
  * @param items -
  *        The items to join.
+ * @param T -
+ *        The type of data to join.
  *
  * @returns
  *        A string that joins the items that are defined, separated by delimiter.
+ *
+ * @example
+ *
+ * ```ts
+ * // 'a b d'
+ * const joinBySpace = joinDefined(' ', 'a', 'b', ['c', false], null, undefined, ['d', true]);
+ * // (Empty String)
+ * const joinEmpty = joinDefined('?');
+ * ```
  */
 export declare function joinDefined<T>(delimiter: string, ...items: JoinListInputParameter<T>[]): string;
 /**
- * Alias to joinList with a string delimiter.
+ * Alias to joinList with a space delimiter.
  *
  * @param items -
  *        The items to join.
+ * @param T -
+ *        The type of data to join.
  *
  * @returns
  *        A string that joins the items that are defined, separated by space delimiter.
+ *
+ * @see
+ *        {@link joinDefined} for more information and examples.
  */
 export declare const spaceJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string;
 /**
@@ -26,9 +52,14 @@ export declare const spaceJoinDefined: <T>(...items: JoinListInputParameter<T>[]
  *
  * @param items -
  *        The items to join.
+ * @param T -
+ *        The type of data to join.
  *
  * @returns
  *        A string that joins the items that are defined, separated by a space delimiter.
+ *
+ * @see
+ *        {@link joinDefined} for more information and examples.
  */
 export declare const cssJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string;
 /**
@@ -36,9 +67,14 @@ export declare const cssJoinDefined: <T>(...items: JoinListInputParameter<T>[])
  *
  * @param items -
  *        The items to join.
+ * @param T -
+ *        The type of data to join.
  *
  * @returns
  *        A string that joins the items that are defined, separated by a comma delimiter.
+ *
+ * @see
+ *        {@link joinDefined} for more information and examples.
  */
 export declare const commaJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string;
 /**
@@ -46,9 +82,14 @@ export declare const commaJoinDefined: <T>(...items: JoinListInputParameter<T>[]
  *
  * @param items -
  *        The items to join.
+ * @param T -
+ *        The type of data to join.
  *
  * @returns
  *        A string that joins the items that are defined, separated by a semi-colon delimiter.
+ *
+ * @see
+ *        {@link joinDefined} for more information and examples.
  */
 export declare const semiColonJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string;
 /**
@@ -56,8 +97,13 @@ export declare const semiColonJoinDefined: <T>(...items: JoinListInputParameter<
  *
  * @param items -
  *        The items to join.
+ * @param T -
+ *        The type of data to join.
  *
  * @returns
  *        A string that joins the items that are defined, separated by a pipe delimiter.
+ *
+ * @see
+ *        {@link joinDefined} for more information and examples.
  */
 export declare const pipeJoinDefined: <T>(...items: JoinListInputParameter<T>[]) => string;

package/dist/types/obligation/obligation.d.ts

@@ -0,0 +1,62 @@
+/**
+ * A specific set of possible values that need to be checked for requirements.
+ *
+ * @param T -
+ *        The type of value that is being checked.
+ */
+export type ZObligatedValue<T> = T | null | undefined | Promise<T | null | undefined>;
+/**
+ * Requires a value to be non null.
+ *
+ * @param val -
+ *        The value to require.  This can be a promise
+ *        that can return null or undefined in addition to the
+ *        value.
+ * @param T -
+ *        The type of value that is being checked.
+ *
+ * @returns
+ *        This method returns val if it is not null
+ *        or undefined, otherwise, an error is thrown.
+ *
+ * @throws
+ *        An error if the value is null or undefined.
+ */
+export declare function required<T>(val: ZObligatedValue<T>): Promise<T>;
+/**
+ * Allows a value to be null or undefined and has a fallback.
+ *
+ * @param val -
+ *        The value to check.  This can be a promise
+ *        that can return null or undefined in addition to the
+ *        value.
+ * @param fallback -
+ *        The fallback value in the case that val is
+ *        null or undefined.
+ * @param T -
+ *        The type of value that is being checked.
+ *
+ * @returns
+ *        This method returns val if it is not null
+ *        or undefined, otherwise, the fallback is returned.
+ *        If val is a promise and rejects, then fallback is
+ *        also returned.
+ */
+export declare function optional<T>(val: ZObligatedValue<T>, fallback: T): Promise<T>;
+/**
+ * Allows a value to be null or undefined and has a fallback.
+ *
+ * @param val -
+ *        The value to check.  This can be a promise
+ *        that can return null or undefined in addition to the
+ *        value.
+ * @param T -
+ *        The type of value that is being checked.
+ *
+ * @returns
+ *        This method returns val if it is not null
+ *        or undefined, otherwise, null is returned.
+ *        If val is a promise and rejects, then null is
+ *        also returned.
+ */
+export declare function optional<T>(val: ZObligatedValue<T>): Promise<T | null>;

package/dist/types/orientation/orientation.d.ts

@@ -3,7 +3,7 @@
  */
 export declare enum ZOrientation {
     /**
-     * Row orientation.
+     * Horizontal orientation.
      *
      * This type of orientation is a row
      * style orientation or flex-row orientation.

package/dist/types/set-first/set-first.d.ts

@@ -1,14 +1,32 @@
 /**
- * Represents a setter function for when you want to set a single value, but you have an array instead.
+ * Represents a setter function for when you want to set a single value,
+ * but you have an array instead.
  *
  * This is useful when you want to support lists of items, but you need
- * backwards compatibility for setting a single item.
+ * backwards compatibility for setting a single item. This is primarily meant
+ * to be use with bind to construct a new method setter that takes an array
+ * and forwards it to a setter method which will accept a single value of the
+ * first item in the target value.
  *
  * @param setValue -
- *        The setter function that takes a single value.
+ *        The setter function that takes a single value.  This will receive
+ *        the first item of the value list.
  * @param fallback -
  *        The fallback value in the case that there are no values.
  * @param value -
  *        The value list to retrieve the first item from.
+ * @param T -
+ *        The type of data that the array holds.
+ *
+ * @example
+ *
+ * ```ts
+ * // An example of a react component that needs a value of an array, but you only care about a single selection.
+ * const [value, setValue] = useState<TypesOfPie>();
+ * const _values = useMemo(() => value ? [value] : [], [value]);
+ * const _setValues = setFirst.bind(null, setValue, undefined);
+ *
+ * return <ComponentWithMultiSelectSupport values={_values} onValuesChange={_setValues} />
+ * ```
  */
 export declare function setFirst<T>(setValue: (val: T) => any, fallback: T, value: T[] | null | undefined): void;

package/dist/types/sleep/sleep.d.ts

@@ -15,8 +15,10 @@ export declare function sleep(ms?: number): Promise<void>;
  *        The total number of milliseconds to sleep.
  * @param val -
  *        The value to resolve with.
+ * @param T -
+ *        The type of value that will be resolved.
  *
  * @returns
- *        A promise that resolves after ms milliseconds.
+ *        A promise that resolves with val after ms milliseconds.
  */
 export declare function sleep<T>(ms: number, val: T): Promise<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zthun/helpful-fn",
-  "version": "2.3.0",
+  "version": "3.0.0",
   "description": "Helpful, isolated pure functions that are not found in other libraries such as lodash.",
   "author": "Anthony Bonta",
   "license": "MIT",
@@ -19,16 +19,15 @@
     "access": "public"
   },
   "dependencies": {
-    "uuid": "^9.0.0"
+    "uuid": "^9.0.1"
   },
   "devDependencies": {
     "microbundle": "^0.15.1",
-    "vite": "^4.4.9",
-    "vitest": "^0.34.3"
+    "vitest": "^0.34.6"
   },
   "files": [
     "dist"
   ],
   "sideEffects": false,
-  "gitHead": "40efb398603f2a29e4c35c1f992b7322e7070d6d"
+  "gitHead": "efd821e16fd4e87a411d3a924b40a2309030539c"
 }