inferred-types 0.51.0 → 0.51.1

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2022-PRESENT Ken Snyder<https://github.com/yankeeinlondon>
+
+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

@@ -1,3 +1,139 @@
-# Inferred Types
 
-This is the TS project which will exported to NPM and simply aggregates the symbols contained from the three other TS projects under `src/`.
+![logo](./inferred-types.png)
+
+## Overview
+
+A collection of Typescript utilities which try to preserve as much strong and narrow typing as is possible. In many cases, these _type utilities_ will be paired with a runtime function which provides a runtime mirror to help keep both design time types and runtime values in sync.
+
+All types -- as well as any pairing runtime functions -- are intended to be "self documenting" as much as is possible. This means that they will _at least_ have a description comment which your editor should expose as a popover. In some cases, there are also code examples included in these comments to further flesh out intended use.
+
+To keep things DRY, the documentation here will be kept to a minimum. This README is intended more as a high level introduction of scope and structure of this repo than documentation.
+
+## Directory Structure
+
+Under the `src/` folder you'll find the the following subdirectories:
+
+- `constants` - a set of runtime constants that can provide _utility_ to both runtime functions as well as provide foundation for enumerated types.
+- `types` - this folder represents the heart of the repo in the form of _type utilities_ and is further broken down by an attempt at functional classification that hopefully aides somewhat in feature discovery.
+- `runtime` - this is where you'll find runtime functions which mutate state while taking care to provide as much as type information that compliments the runtime environment as is possible.
+
+## Runtime synchronization with Types
+
+You will find many runtime functions like `ensureleading(str, substring)` which have a similarly named type (in this case `EnsureLeading<TStr, TSubstring>`). This is no accident and at some future point there may even be something approximating 1:1 parity.
+
+This connection between the type system and the runtime environment allows both a harmonization of variables across both environments and helps to ensure their consistency but it the runtime environment also often really needs strong type utilities to extract out narrow type definitions in the runtime environment.
+
+## Examples
+
+What follows is not meant to be comprehensive set of examples but rather just a sampling that hopefully gives some perspective on the breadth of scope of this library.
+
+### String Literals
+
+#### Casing Conventions
+
+- use `PascalCase<T>`, `CamelCase<T>`, `SnakeCase<T>`, and `KebabCase<T>` to convert a string to one of several familiar naming conventions
+- use `AllCaps<T>` to make all alphanumeric characters into their uppercase variant
+
+#### Pluralization
+
+Convert the _type_ and _value_ of a variable from it's singular form to it's plural form:
+
+```ts
+import { pluralize } from "inferred-types";
+
+// "people"
+const people = pluralize("person");
+```
+
+> **Note:** not only does this utility provide all major grammatical rules used in conversion but has a dictionary of common exceptions it will use too.
+
+#### Consistency with Ensure/Strip utilities
+
+- it's often desireable to _ensure_ that a string _starts with_ or _ends with_ a given string
+- the inverse can also be useful (aka, to _ensure_ a string _does not_ start or end with a given string literal)
+- this library provides `EnsureLeading`, `EnsureTrailing`, `StripLeading`, and `StripTrailing` utilities to meet these type needs
+
+  ```ts
+  import type { EnsureLeading } from "inferred-types";
+  // "start-${string}"
+  type T1 = EnsureLeading<string, "start-">;
+  // "start-with"
+  type T2 = EnsureLeading<"start-with", "start-">;
+  // "start-with"
+  type T3 = EnsureLeading<"with", "start-">;
+  ```
+
+#### Character Sets
+
+- types like `Alpha`, `NumericChar`, `Whitespace`, `Consonants`, etc. try to represent character set building blocks that we may have to isolate on for our own types definitions
+
+#### Data Patterns
+
+- types like `Url`, `IpAddress`, `CSV`, `DotPath`, `Hexadecimal`, `ZipCode`, and `DomainName` attempt to provide an out of the box type for common data structure patterns we find in the real world
+
+### Numeric Literals
+
+- use the `Add<A,B>`, `Subtract<A,B>`, `Increment<T>`, `Decrement<T>` utilities to work with numeric types (or even _numeric_ string literals)
+- get the length of a string or tuple with the `Length<T>` utility
+- ensure an _integer_ value with `Integer<T>`; ensure a _float_ value with `Float<T>`
+- compare numeric literals with `LessThan<A,B>`, `LessThanOrEqual<A,B>`, and `GreaterThan<A,B>`
+- ensure a _positive_ number with `Abs<T>`
+
+### Lists
+
+- Use `AfterFirst`, `First`, `Last` to index into a tuple / list value
+- Use `AsArray<T>` to ensure an array value for T
+- Use `Flatten<T>` to _flatten_ an array
+- Use `Slice<T,S,E>` to take out a subset of elements in a list
+- Use `Reverse` to reverse a list
+
+### Object / Dictionaries
+
+1. Based on an object's entity values:
+
+    Assume a base type of `Obj`:
+
+    ```ts
+    type Obj = {
+        n1: number;
+        n2: 2;
+        n3: 3;
+        success: true;
+        s1: string;
+        s2: "hello";
+    }
+    ```
+
+    We can get a union of string literals representing the _keys_ on the object whose value _extends_ some value:
+
+    ```ts
+    import type { KeysWithValue, KeysWithoutValue } from "inferred-types";
+    // "s1" | "s2"
+    type S = KeysWithValue<Obj, string>;
+    // "success" | "n1" | "n2"
+    type N = KeysWithoutValue<Obj, string>;
+    ```
+
+    > though less used, you can also use `KeysEqualValue` and `KeysNotEqualValue` for equality matching
+
+    If you'd prefer to mutate the object's type rather than just identify the _keys_ which extend a value you can do this with: `WithValue` and `WithoutValue`:
+
+     ```ts
+     import type { WithValue, WithoutValue } from "inferred-types";
+     // { s1: string; s2: "hello" }
+     type S = WithValue<Obj, string>;
+     // { success: true; n1: number; n2: 2; n3: 3 }
+     type N = WithoutValue<Obj, string>;
+     ```
+
+## Contributing
+
+If you are using this library and would like to take the next step of _contributing_; that effort is welcome but please do make sure to always provide both runtime and type tests for any code changes which you submit as a pull request.
+
+See the plentiful examples that exist under the `tests/` folder for inspiration.
+
+**Note:** as of 2024 I'm also starting to add "type performance" tests; not an absolute requirement but in general adding something like you'll find in the `benches/` folder for any new type utility would be appreciated.
+
+## Licensing
+
+This repo is offered under the highly permissive MIT license.

package/dist/constants/Alpha.d.ts

@@ -0,0 +1,13 @@
+/**
+ * An array of all the lower-cased alphabetic characters
+ */
+export declare const LOWER_ALPHA_CHARS: readonly ["a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z"];
+/**
+ * An array of all the upper-cased alphabetic characters
+ */
+export declare const UPPER_ALPHA_CHARS: readonly ["A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z"];
+/**
+ * An array of all alphabetic characters (upper and lower)
+ */
+export declare const ALPHA_CHARS: readonly ["a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z", "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z"];
+//# sourceMappingURL=Alpha.d.ts.map

package/dist/constants/Alpha.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Alpha.d.ts","sourceRoot":"","sources":["../../src/constants/Alpha.ts"],"names":[],"mappings":"AACA;;GAEG;AACH,eAAO,MAAM,iBAAiB,6IACoF,CAAC;AAEnH;;GAEG;AACH,eAAO,MAAM,iBAAiB,6IAEpB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,WAAW,+QAGd,CAAC"}

package/dist/constants/Alpha.js

@@ -0,0 +1,19 @@
+/**
+ * An array of all the lower-cased alphabetic characters
+ */
+export const LOWER_ALPHA_CHARS = [
+    "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z",
+];
+/**
+ * An array of all the upper-cased alphabetic characters
+ */
+export const UPPER_ALPHA_CHARS = [
+    "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z"
+];
+/**
+ * An array of all alphabetic characters (upper and lower)
+ */
+export const ALPHA_CHARS = [
+    ...LOWER_ALPHA_CHARS,
+    ...UPPER_ALPHA_CHARS
+];

package/dist/constants/Books.d.ts

@@ -0,0 +1,2 @@
+export declare const AMAZON_BOOKS: readonly ["https://www.amazon.com/{{ string }}storeType=ebooks{{ string }}", "https://www.amazon.com/{{ string }}ref=tmm_hrd_swatch{{ string }}", "https://www.amazon.com/{{ string }}ref=tmm_pap_swatch{{ string }}", "https://www.amazon.com/{{ string }}ref=tmm_aud_swatch{{ string }}", "https://www.amazon.com/books-used-books-textbooks/{{ string }}"];
+//# sourceMappingURL=Books.d.ts.map

package/dist/constants/Books.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Books.d.ts","sourceRoot":"","sources":["../../src/constants/Books.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY,+VAMf,CAAC"}

package/dist/constants/Books.js

@@ -0,0 +1,8 @@
+const string = `{{ string }}`;
+export const AMAZON_BOOKS = [
+    `https://www.amazon.com/${string}storeType=ebooks${string}`,
+    `https://www.amazon.com/${string}ref=tmm_hrd_swatch${string}`,
+    `https://www.amazon.com/${string}ref=tmm_pap_swatch${string}`,
+    `https://www.amazon.com/${string}ref=tmm_aud_swatch${string}`,
+    `https://www.amazon.com/books-used-books-textbooks/${string}`
+];

package/dist/constants/Characters.d.ts

@@ -0,0 +1,2 @@
+export declare const WHITESPACE_CHARS: readonly [" ", "\n", "\t", "\b"];
+//# sourceMappingURL=Characters.d.ts.map

package/dist/constants/Characters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Characters.d.ts","sourceRoot":"","sources":["../../src/constants/Characters.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,kCAKnB,CAAC"}

package/dist/constants/Characters.js

@@ -0,0 +1,6 @@
+export const WHITESPACE_CHARS = [
+    " ",
+    "\n",
+    "\t",
+    "\b"
+];

package/dist/constants/Comma.d.ts

@@ -0,0 +1,16 @@
+/**
+ * **COMMA**
+ *
+ * A constant used for serializing a comma in cases
+ * where a comma has special meaning (for instance
+ * CSV data where a raw comma is considered a
+ * separator)
+ */
+export declare const COMMA: import("inferred-types/dist/constants/index").Constant<"comma">;
+/**
+ * **SerializedComma**
+ *
+ * A serialized representation of a `,` value.
+ */
+export type SerializedComma = typeof COMMA;
+//# sourceMappingURL=Comma.d.ts.map

package/dist/constants/Comma.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Comma.d.ts","sourceRoot":"","sources":["../../src/constants/Comma.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,iEAA0B,CAAC;AAE7C;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,KAAK,CAAC"}

package/dist/constants/Comma.js

@@ -0,0 +1,10 @@
+import { createConstant } from "inferred-types/dist/constants/index";
+/**
+ * **COMMA**
+ *
+ * A constant used for serializing a comma in cases
+ * where a comma has special meaning (for instance
+ * CSV data where a raw comma is considered a
+ * separator)
+ */
+export const COMMA = createConstant("comma");

package/dist/constants/CommonObjProps.d.ts

@@ -0,0 +1,12 @@
+export type CommonObjProps = [
+    "id",
+    "type",
+    "kind",
+    "_type",
+    "_kind",
+    "key",
+    "value",
+    "name"
+];
+export declare const COMMON_OBJ_PROPS: readonly ["id", "type", "kind", "_type", "_kind", "key", "value", "name"];
+//# sourceMappingURL=CommonObjProps.d.ts.map

package/dist/constants/CommonObjProps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommonObjProps.d.ts","sourceRoot":"","sources":["../../src/constants/CommonObjProps.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI;IAAE,MAAM;IAAE,MAAM;IAAE,OAAO;IAAE,OAAO;IAAE,KAAK;IAAE,OAAO;IAAE,MAAM;CAC/D,CAAC;AAEF,eAAO,MAAM,gBAAgB,2EAEnB,CAAC"}

package/dist/constants/CommonObjProps.js

@@ -0,0 +1,3 @@
+export const COMMON_OBJ_PROPS = [
+    "id", "type", "kind", "_type", "_kind", "key", "value", "name"
+];

package/dist/constants/Consonants.d.ts

@@ -0,0 +1,2 @@
+export declare const CONSONANTS: readonly ["b", "c", "d", "f", "g", "h", "j", "k", "l", "m", "n", "p", "q", "r", "s", "t", "v", "w", "x", "z", "y"];
+//# sourceMappingURL=Consonants.d.ts.map

package/dist/constants/Consonants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Consonants.d.ts","sourceRoot":"","sources":["../../src/constants/Consonants.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,UAAU,oHAsBb,CAAC"}

package/dist/constants/Consonants.js

@@ -0,0 +1,23 @@
+export const CONSONANTS = [
+    "b",
+    "c",
+    "d",
+    "f",
+    "g",
+    "h",
+    "j",
+    "k",
+    "l",
+    "m",
+    "n",
+    "p",
+    "q",
+    "r",
+    "s",
+    "t",
+    "v",
+    "w",
+    "x",
+    "z",
+    "y",
+];

package/dist/constants/Constant.d.ts

@@ -0,0 +1,11 @@
+/**
+ * **Constant**`<TKind>`
+ *
+ * A static value of a particular _kind_.
+ */
+export type Constant<TKind extends string, TVal = unknown> = {
+    _type: "Constant";
+    kind: TKind;
+    value: TVal;
+};
+//# sourceMappingURL=Constant.d.ts.map

package/dist/constants/Constant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Constant.d.ts","sourceRoot":"","sources":["../../src/constants/Constant.ts"],"names":[],"mappings":"AACA;;;;GAIG;AACH,MAAM,MAAM,QAAQ,CAAC,KAAK,SAAS,MAAM,EAAE,IAAI,GAAG,OAAO,IAAI;IAC3D,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,IAAI,CAAC;CACb,CAAC"}

package/dist/constants/Constant.js

@@ -0,0 +1 @@
+export {};

package/dist/constants/DateTime.d.ts

@@ -0,0 +1,13 @@
+/**
+ * **MONTH_NAME**
+ *
+ * Full month names.
+ */
+export declare const MONTH_NAME: readonly ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
+/**
+ * **MONTH_ABBR**
+ *
+ * Abbreviated month names.
+ */
+export declare const MONTH_ABBR: readonly ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+//# sourceMappingURL=DateTime.d.ts.map

package/dist/constants/DateTime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DateTime.d.ts","sourceRoot":"","sources":["../../src/constants/DateTime.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,UAAU,qIAab,CAAC;AAGX;;;;GAIG;AACH,eAAO,MAAM,UAAU,+FAab,CAAC"}

package/dist/constants/DateTime.js

@@ -0,0 +1,38 @@
+/**
+ * **MONTH_NAME**
+ *
+ * Full month names.
+ */
+export const MONTH_NAME = [
+    "January",
+    "February",
+    "March",
+    "April",
+    "May",
+    "June",
+    "July",
+    "August",
+    "September",
+    "October",
+    "November",
+    "December"
+];
+/**
+ * **MONTH_ABBR**
+ *
+ * Abbreviated month names.
+ */
+export const MONTH_ABBR = [
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec"
+];

package/dist/constants/FalsyValues.d.ts

@@ -0,0 +1,8 @@
+/**
+ * **FALSY_VALUES**
+ *
+ * A tuple which contains all values which are considered _falsy_ in
+ * Javascript.
+ */
+export declare const FALSY_VALUES: readonly [false, 0, 0, "", null, undefined, number];
+//# sourceMappingURL=FalsyValues.d.ts.map

package/dist/constants/FalsyValues.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FalsyValues.d.ts","sourceRoot":"","sources":["../../src/constants/FalsyValues.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,YAAY,qDAEf,CAAC"}

package/dist/constants/FalsyValues.js

@@ -0,0 +1,9 @@
+/**
+ * **FALSY_VALUES**
+ *
+ * A tuple which contains all values which are considered _falsy_ in
+ * Javascript.
+ */
+export const FALSY_VALUES = [
+    false, 0, -0, "", null, undefined, Number.NaN
+];

package/dist/constants/Functional.d.ts

@@ -0,0 +1,19 @@
+/**
+ * **RESULT**
+ *
+ * Concrete values for `Ok` and `Err` states.
+ */
+export declare const RESULT: {
+    readonly Ok: "ok";
+    readonly Err: "err";
+};
+/**
+ * **OPTION**
+ *
+ * Concrete values for `Some` and `None` states.
+ */
+export declare const OPTION: {
+    readonly Some: 1;
+    readonly None: 0;
+};
+//# sourceMappingURL=Functional.d.ts.map

package/dist/constants/Functional.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Functional.d.ts","sourceRoot":"","sources":["../../src/constants/Functional.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,MAAM;;;CAGT,CAAC;AAGX;;;;GAIG;AACH,eAAO,MAAM,MAAM;;;CAGT,CAAC"}

package/dist/constants/Functional.js

@@ -0,0 +1,18 @@
+/**
+ * **RESULT**
+ *
+ * Concrete values for `Ok` and `Err` states.
+ */
+export const RESULT = {
+    Ok: "ok",
+    Err: "err"
+};
+/**
+ * **OPTION**
+ *
+ * Concrete values for `Some` and `None` states.
+ */
+export const OPTION = {
+    Some: 1,
+    None: 0
+};