@zthun/trilean 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Anthony Bonta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# Trilean
+
+Adds a three state logic type. The values can be true, false, and indeterminate.
+
+## Installation
+
+```sh
+# NPM
+npm install @zthun/trilean
+# Yarn
+yarn add @zthun/trilean
+```
+
+## Usage
+
+```ts
+import { trilean, ZTrilean } from '@zthun/trilean';
+
+const checked: trilean = true;
+const unchecked: trilean = false;
+const indeterminate: trilean = ZTrilean.Indeterminate;
+
+// Returns 'true'
+ZTrilean.stringify(checked);
+// Returns 'false'
+ZTrilean.stringify(unchecked);
+// Returns 'indeterminate'
+ZTrilean.stringify(indeterminate);
+
+// Returns true
+ZTrilean.parse('true');
+// Returns false
+ZTrilean.parse('false');
+// Returns ZTrilean.Indeterminate
+ZTrilean.parse('indeterminate');
+// Returns false
+ZTrilean.parse(null);
+// Returns true fallback.
+ZTrilean.parse('not-a-trilean', true);
+
+// Returns true
+ZTrilean.is(true);
+ZTrilean.is(false);
+ZTrilean.is(ZTrilean.Indeterminate);
+// Returns false
+ZTrilean.is('string is not a trilean');
+// Returns true - This is mostly for typescript type guard support.
+ZTrilean.isIndeterminate(ZTrilean.Indeterminate);
+
+// Convert any value to a trilean.
+const kindaTrue = ZTrilean.convert('A truthy value');
+const kindaFalse = ZTrilean.convert(0);
+const alsoIndeterminate = ZTrilean.convert(ZTrilean.Indeterminate);
+```

package/dist/index.cjs

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const _ZTrilean = class _ZTrilean {
+  /**
+   * Converts a trilean value to a string.
+   *
+   * @param x -
+   *        The value to convert.
+   *
+   * @returns
+   *        A string of true if x is true, false if x is false,
+   *        and indeterminate if x is the indeterminate symbol.
+   */
+  static stringify(x) {
+    return _ZTrilean.isIndeterminate(x) ? x.description : String(x);
+  }
+  /**
+   * Converts a string to a trilean value.
+   *
+   * @param str -
+   *        The text to parse.
+   * @param fallback -
+   *        The fallback in the case that str is not a parsable value.
+   *
+   * @returns
+   *        The parsed trilean value or fallback if str is not a valid
+   *        trilean value.
+   */
+  static parse(str, fallback = false) {
+    if ((str == null ? void 0 : str.toUpperCase().localeCompare("TRUE")) === 0) {
+      return true;
+    }
+    if ((str == null ? void 0 : str.toUpperCase().localeCompare("FALSE")) === 0) {
+      return false;
+    }
+    if ((str == null ? void 0 : str.toUpperCase().localeCompare("INDETERMINATE")) === 0) {
+      return _ZTrilean.Indeterminate;
+    }
+    return fallback;
+  }
+  /**
+   * Gets a value that determines if val is a trilean supported value.
+   *
+   * @param val -
+   *        The value to test.
+   *
+   * @returns
+   *        True if val is a trilean value.  False otherwise.
+   */
+  static is(val) {
+    return typeof val === "boolean" || _ZTrilean.isIndeterminate(val);
+  }
+  /**
+   * Gets whether val is the indeterminate value.
+   */
+  static isIndeterminate(val) {
+    return val === _ZTrilean.Indeterminate;
+  }
+  /**
+   * Converts from a value to a trilean value.
+   *
+   * This is similar to parse, but it also supports non
+   * string inputs which will be converted to a boolean.
+   *
+   * @param val -
+   *        The value to convert.
+   * @param fallback -
+   *        The fallback value in the case that val cannot be converted. This will
+   *        only be used in the case that val is a string, null, or undefined.
+   *
+   * @returns
+   *        The trilean value of val.  If val is null or undefined, then
+   *        fallback is returned.  If val is a string, then the return value of
+   *        {@link parse} will be used.  If val is a boolean, then it will be
+   *        directly returned.  If val is equal to {@link Indeterminate}, then
+   *        {@link Indeterminate} will be returned.  Otherwise, the truthy
+   *        nature of value will be returned.
+   */
+  static convert(val, fallback = false) {
+    if (val == null) {
+      return fallback;
+    }
+    if (_ZTrilean.is(val)) {
+      return val;
+    }
+    if (typeof val === "string") {
+      return _ZTrilean.parse(val, fallback);
+    }
+    return !!val;
+  }
+};
+_ZTrilean.Indeterminate = Symbol("indeterminate");
+let ZTrilean = _ZTrilean;
+exports.ZTrilean = ZTrilean;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../src/trilean.mts"],"sourcesContent":["/**\n * Represents a tri logic state.\n *\n * See {@link ZTrilean.Indeterminate} for what the symbol value should be.\n */\nexport type trilean = boolean | symbol;\n\n/**\n * A utility class for trilean values.\n */\nexport abstract class ZTrilean {\n  /**\n   * A unique value for the third, indeterminate, state.\n   */\n  public static readonly Indeterminate = Symbol('indeterminate');\n\n  /**\n   * Converts a trilean value to a string.\n   *\n   * @param x -\n   *        The value to convert.\n   *\n   * @returns\n   *        A string of true if x is true, false if x is false,\n   *        and indeterminate if x is the indeterminate symbol.\n   */\n  public static stringify(x: trilean): string {\n    return ZTrilean.isIndeterminate(x) ? x.description! : String(x);\n  }\n\n  /**\n   * Converts a string to a trilean value.\n   *\n   * @param str -\n   *        The text to parse.\n   * @param fallback -\n   *        The fallback in the case that str is not a parsable value.\n   *\n   * @returns\n   *        The parsed trilean value or fallback if str is not a valid\n   *        trilean value.\n   */\n  public static parse(str: string | null | undefined, fallback: trilean = false): trilean {\n    if (str?.toUpperCase().localeCompare('TRUE') === 0) {\n      return true;\n    }\n\n    if (str?.toUpperCase().localeCompare('FALSE') === 0) {\n      return false;\n    }\n\n    if (str?.toUpperCase().localeCompare('INDETERMINATE') === 0) {\n      return ZTrilean.Indeterminate;\n    }\n\n    return fallback;\n  }\n\n  /**\n   * Gets a value that determines if val is a trilean supported value.\n   *\n   * @param val -\n   *        The value to test.\n   *\n   * @returns\n   *        True if val is a trilean value.  False otherwise.\n   */\n  public static is(val: any): val is trilean {\n    return typeof val === 'boolean' || ZTrilean.isIndeterminate(val);\n  }\n\n  /**\n   * Gets whether val is the indeterminate value.\n   */\n  public static isIndeterminate(val: trilean): val is symbol {\n    return val === ZTrilean.Indeterminate;\n  }\n\n  /**\n   * Converts from a value to a trilean value.\n   *\n   * This is similar to parse, but it also supports non\n   * string inputs which will be converted to a boolean.\n   *\n   * @param val -\n   *        The value to convert.\n   * @param fallback -\n   *        The fallback value in the case that val cannot be converted. This will\n   *        only be used in the case that val is a string, null, or undefined.\n   *\n   * @returns\n   *        The trilean value of val.  If val is null or undefined, then\n   *        fallback is returned.  If val is a string, then the return value of\n   *        {@link parse} will be used.  If val is a boolean, then it will be\n   *        directly returned.  If val is equal to {@link Indeterminate}, then\n   *        {@link Indeterminate} will be returned.  Otherwise, the truthy\n   *        nature of value will be returned.\n   */\n  public static convert(val: any, fallback: trilean = false): trilean {\n    if (val == null) {\n      return fallback;\n    }\n\n    if (ZTrilean.is(val)) {\n      return val;\n    }\n\n    if (typeof val === 'string') {\n      return ZTrilean.parse(val, fallback);\n    }\n\n    return !!val;\n  }\n}\n"],"names":[],"mappings":";;AAUO,MAAe,YAAf,MAAe,UAAS;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAgB7B,OAAc,UAAU,GAAoB;AAC1C,WAAO,UAAS,gBAAgB,CAAC,IAAI,EAAE,cAAe,OAAO,CAAC;AAAA,EAChE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAcA,OAAc,MAAM,KAAgC,WAAoB,OAAgB;AACtF,SAAI,2BAAK,cAAc,cAAc,aAAY,GAAG;AAC3C,aAAA;AAAA,IACT;AAEA,SAAI,2BAAK,cAAc,cAAc,cAAa,GAAG;AAC5C,aAAA;AAAA,IACT;AAEA,SAAI,2BAAK,cAAc,cAAc,sBAAqB,GAAG;AAC3D,aAAO,UAAS;AAAA,IAClB;AAEO,WAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,OAAc,GAAG,KAA0B;AACzC,WAAO,OAAO,QAAQ,aAAa,UAAS,gBAAgB,GAAG;AAAA,EACjE;AAAA;AAAA;AAAA;AAAA,EAKA,OAAc,gBAAgB,KAA6B;AACzD,WAAO,QAAQ,UAAS;AAAA,EAC1B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAsBA,OAAc,QAAQ,KAAU,WAAoB,OAAgB;AAClE,QAAI,OAAO,MAAM;AACR,aAAA;AAAA,IACT;AAEI,QAAA,UAAS,GAAG,GAAG,GAAG;AACb,aAAA;AAAA,IACT;AAEI,QAAA,OAAO,QAAQ,UAAU;AACpB,aAAA,UAAS,MAAM,KAAK,QAAQ;AAAA,IACrC;AAEA,WAAO,CAAC,CAAC;AAAA,EACX;AACF;AAnGyB,UAAA,gBAAgB,OAAO,eAAe;AAJxD,IAAe,WAAf;;"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './intrinsic.mjs';
+export * from './trilean.mjs';

package/dist/index.js

@@ -0,0 +1,95 @@
+const _ZTrilean = class _ZTrilean {
+  /**
+   * Converts a trilean value to a string.
+   *
+   * @param x -
+   *        The value to convert.
+   *
+   * @returns
+   *        A string of true if x is true, false if x is false,
+   *        and indeterminate if x is the indeterminate symbol.
+   */
+  static stringify(x) {
+    return _ZTrilean.isIndeterminate(x) ? x.description : String(x);
+  }
+  /**
+   * Converts a string to a trilean value.
+   *
+   * @param str -
+   *        The text to parse.
+   * @param fallback -
+   *        The fallback in the case that str is not a parsable value.
+   *
+   * @returns
+   *        The parsed trilean value or fallback if str is not a valid
+   *        trilean value.
+   */
+  static parse(str, fallback = false) {
+    if ((str == null ? void 0 : str.toUpperCase().localeCompare("TRUE")) === 0) {
+      return true;
+    }
+    if ((str == null ? void 0 : str.toUpperCase().localeCompare("FALSE")) === 0) {
+      return false;
+    }
+    if ((str == null ? void 0 : str.toUpperCase().localeCompare("INDETERMINATE")) === 0) {
+      return _ZTrilean.Indeterminate;
+    }
+    return fallback;
+  }
+  /**
+   * Gets a value that determines if val is a trilean supported value.
+   *
+   * @param val -
+   *        The value to test.
+   *
+   * @returns
+   *        True if val is a trilean value.  False otherwise.
+   */
+  static is(val) {
+    return typeof val === "boolean" || _ZTrilean.isIndeterminate(val);
+  }
+  /**
+   * Gets whether val is the indeterminate value.
+   */
+  static isIndeterminate(val) {
+    return val === _ZTrilean.Indeterminate;
+  }
+  /**
+   * Converts from a value to a trilean value.
+   *
+   * This is similar to parse, but it also supports non
+   * string inputs which will be converted to a boolean.
+   *
+   * @param val -
+   *        The value to convert.
+   * @param fallback -
+   *        The fallback value in the case that val cannot be converted. This will
+   *        only be used in the case that val is a string, null, or undefined.
+   *
+   * @returns
+   *        The trilean value of val.  If val is null or undefined, then
+   *        fallback is returned.  If val is a string, then the return value of
+   *        {@link parse} will be used.  If val is a boolean, then it will be
+   *        directly returned.  If val is equal to {@link Indeterminate}, then
+   *        {@link Indeterminate} will be returned.  Otherwise, the truthy
+   *        nature of value will be returned.
+   */
+  static convert(val, fallback = false) {
+    if (val == null) {
+      return fallback;
+    }
+    if (_ZTrilean.is(val)) {
+      return val;
+    }
+    if (typeof val === "string") {
+      return _ZTrilean.parse(val, fallback);
+    }
+    return !!val;
+  }
+};
+_ZTrilean.Indeterminate = Symbol("indeterminate");
+let ZTrilean = _ZTrilean;
+export {
+  ZTrilean
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/trilean.mts"],"sourcesContent":["/**\n * Represents a tri logic state.\n *\n * See {@link ZTrilean.Indeterminate} for what the symbol value should be.\n */\nexport type trilean = boolean | symbol;\n\n/**\n * A utility class for trilean values.\n */\nexport abstract class ZTrilean {\n  /**\n   * A unique value for the third, indeterminate, state.\n   */\n  public static readonly Indeterminate = Symbol('indeterminate');\n\n  /**\n   * Converts a trilean value to a string.\n   *\n   * @param x -\n   *        The value to convert.\n   *\n   * @returns\n   *        A string of true if x is true, false if x is false,\n   *        and indeterminate if x is the indeterminate symbol.\n   */\n  public static stringify(x: trilean): string {\n    return ZTrilean.isIndeterminate(x) ? x.description! : String(x);\n  }\n\n  /**\n   * Converts a string to a trilean value.\n   *\n   * @param str -\n   *        The text to parse.\n   * @param fallback -\n   *        The fallback in the case that str is not a parsable value.\n   *\n   * @returns\n   *        The parsed trilean value or fallback if str is not a valid\n   *        trilean value.\n   */\n  public static parse(str: string | null | undefined, fallback: trilean = false): trilean {\n    if (str?.toUpperCase().localeCompare('TRUE') === 0) {\n      return true;\n    }\n\n    if (str?.toUpperCase().localeCompare('FALSE') === 0) {\n      return false;\n    }\n\n    if (str?.toUpperCase().localeCompare('INDETERMINATE') === 0) {\n      return ZTrilean.Indeterminate;\n    }\n\n    return fallback;\n  }\n\n  /**\n   * Gets a value that determines if val is a trilean supported value.\n   *\n   * @param val -\n   *        The value to test.\n   *\n   * @returns\n   *        True if val is a trilean value.  False otherwise.\n   */\n  public static is(val: any): val is trilean {\n    return typeof val === 'boolean' || ZTrilean.isIndeterminate(val);\n  }\n\n  /**\n   * Gets whether val is the indeterminate value.\n   */\n  public static isIndeterminate(val: trilean): val is symbol {\n    return val === ZTrilean.Indeterminate;\n  }\n\n  /**\n   * Converts from a value to a trilean value.\n   *\n   * This is similar to parse, but it also supports non\n   * string inputs which will be converted to a boolean.\n   *\n   * @param val -\n   *        The value to convert.\n   * @param fallback -\n   *        The fallback value in the case that val cannot be converted. This will\n   *        only be used in the case that val is a string, null, or undefined.\n   *\n   * @returns\n   *        The trilean value of val.  If val is null or undefined, then\n   *        fallback is returned.  If val is a string, then the return value of\n   *        {@link parse} will be used.  If val is a boolean, then it will be\n   *        directly returned.  If val is equal to {@link Indeterminate}, then\n   *        {@link Indeterminate} will be returned.  Otherwise, the truthy\n   *        nature of value will be returned.\n   */\n  public static convert(val: any, fallback: trilean = false): trilean {\n    if (val == null) {\n      return fallback;\n    }\n\n    if (ZTrilean.is(val)) {\n      return val;\n    }\n\n    if (typeof val === 'string') {\n      return ZTrilean.parse(val, fallback);\n    }\n\n    return !!val;\n  }\n}\n"],"names":[],"mappings":"AAUO,MAAe,YAAf,MAAe,UAAS;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAgB7B,OAAc,UAAU,GAAoB;AAC1C,WAAO,UAAS,gBAAgB,CAAC,IAAI,EAAE,cAAe,OAAO,CAAC;AAAA,EAChE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAcA,OAAc,MAAM,KAAgC,WAAoB,OAAgB;AACtF,SAAI,2BAAK,cAAc,cAAc,aAAY,GAAG;AAC3C,aAAA;AAAA,IACT;AAEA,SAAI,2BAAK,cAAc,cAAc,cAAa,GAAG;AAC5C,aAAA;AAAA,IACT;AAEA,SAAI,2BAAK,cAAc,cAAc,sBAAqB,GAAG;AAC3D,aAAO,UAAS;AAAA,IAClB;AAEO,WAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,OAAc,GAAG,KAA0B;AACzC,WAAO,OAAO,QAAQ,aAAa,UAAS,gBAAgB,GAAG;AAAA,EACjE;AAAA;AAAA;AAAA;AAAA,EAKA,OAAc,gBAAgB,KAA6B;AACzD,WAAO,QAAQ,UAAS;AAAA,EAC1B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAsBA,OAAc,QAAQ,KAAU,WAAoB,OAAgB;AAClE,QAAI,OAAO,MAAM;AACR,aAAA;AAAA,IACT;AAEI,QAAA,UAAS,GAAG,GAAG,GAAG;AACb,aAAA;AAAA,IACT;AAEI,QAAA,OAAO,QAAQ,UAAU;AACpB,aAAA,UAAS,MAAM,KAAK,QAAQ;AAAA,IACrC;AAEA,WAAO,CAAC,CAAC;AAAA,EACX;AACF;AAnGyB,UAAA,gBAAgB,OAAO,eAAe;AAJxD,IAAe,WAAf;"}

package/dist/intrinsic.d.mts

@@ -0,0 +1,4 @@
+/**
+ * Intrinsic types as a type.
+ */
+export type ZIntrinsic = 'bigint' | 'boolean' | 'function' | 'number' | 'object' | 'string' | 'symbol' | 'trilean';

package/dist/trilean.d.mts

@@ -0,0 +1,74 @@
+/**
+ * Represents a tri logic state.
+ *
+ * See {@link ZTrilean.Indeterminate} for what the symbol value should be.
+ */
+export type trilean = boolean | symbol;
+/**
+ * A utility class for trilean values.
+ */
+export declare abstract class ZTrilean {
+    /**
+     * A unique value for the third, indeterminate, state.
+     */
+    static readonly Indeterminate: unique symbol;
+    /**
+     * Converts a trilean value to a string.
+     *
+     * @param x -
+     *        The value to convert.
+     *
+     * @returns
+     *        A string of true if x is true, false if x is false,
+     *        and indeterminate if x is the indeterminate symbol.
+     */
+    static stringify(x: trilean): string;
+    /**
+     * Converts a string to a trilean value.
+     *
+     * @param str -
+     *        The text to parse.
+     * @param fallback -
+     *        The fallback in the case that str is not a parsable value.
+     *
+     * @returns
+     *        The parsed trilean value or fallback if str is not a valid
+     *        trilean value.
+     */
+    static parse(str: string | null | undefined, fallback?: trilean): trilean;
+    /**
+     * Gets a value that determines if val is a trilean supported value.
+     *
+     * @param val -
+     *        The value to test.
+     *
+     * @returns
+     *        True if val is a trilean value.  False otherwise.
+     */
+    static is(val: any): val is trilean;
+    /**
+     * Gets whether val is the indeterminate value.
+     */
+    static isIndeterminate(val: trilean): val is symbol;
+    /**
+     * Converts from a value to a trilean value.
+     *
+     * This is similar to parse, but it also supports non
+     * string inputs which will be converted to a boolean.
+     *
+     * @param val -
+     *        The value to convert.
+     * @param fallback -
+     *        The fallback value in the case that val cannot be converted. This will
+     *        only be used in the case that val is a string, null, or undefined.
+     *
+     * @returns
+     *        The trilean value of val.  If val is null or undefined, then
+     *        fallback is returned.  If val is a string, then the return value of
+     *        {@link parse} will be used.  If val is a boolean, then it will be
+     *        directly returned.  If val is equal to {@link Indeterminate}, then
+     *        {@link Indeterminate} will be returned.  Otherwise, the truthy
+     *        nature of value will be returned.
+     */
+    static convert(val: any, fallback?: trilean): trilean;
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@zthun/trilean",
+  "version": "1.1.0",
+  "description": "A tri state boolean logic type.",
+  "author": "Anthony Bonta",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zthun/trilean",
+    "directory": "packages/trilean"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "require": "./dist/index.cjs",
+    "import": "./dist/index.js",
+    "types": "./dist/index.d.ts"
+  },
+  "scripts": {
+    "build": "vite build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "~5.4.3",
+    "vite": "^5.2.7",
+    "vitest": "^1.4.0",
+    "vitest-mock-extended": "^1.3.1"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "gitHead": "c616fb580f4334703d6a5bdf4c1936d31a75aaff"
+}