inferred-types 0.41.2 → 0.41.3

package/README.md

@@ -1,53 +1,85 @@
-# Inferred Types
 
-A collection of Typescript utilities which try to preserve as much strong and narrow typing as is possible. The repo's `src/` directory ia broken into a set of **runtime** utilities as well as pure **design-time** type utilities.
+![logo](./inferred-types.png)
 
-All utilities are tested for runtime and design-time correctness.
+## Overview
 
-Below you'll find a cursory set of examples of both _type_ and _runtime_ utilities which are provided. For a complete list always refer to the fully typed symbols exported from this repo or the tests (both runtime and type tests) which should describe expected behavior.
+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.
 
-## Type Utilities
+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.
+
+## 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
 
-1. Change casing:
+#### Casing Conventions
 
-    - use `PascalCase<T>`, `CamelCase<T>`, `SnakeCase<T>`, and `KebabCase<T>` to convert a string to a particular string naming convention.
-    - ensure the _leading_ or _trailing_ part of a string is known:
+- 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
 
-        ```ts
-        import type { EnsureLeading } from "inferred-types";
-        // "start-${string}"
-        type T1 = EnsureLeading<string, "start-">;
-        // "start-with"
-        type T2 = EnsureLeading<"start-with", "start-">;
-        ```
+#### Pluralization
 
-        - you can also use `EnsureTrailing` for the end of the string
-        - use `StripLeading`/`StripTrailing` to perform the opposite functionality
+Convert the _type_ and _value_ of a variable from it's singular form to it's plural form:
 
-2. Work with string length:
+```ts
+import { pluralize } from "inferred-types";
 
-    ```ts
-    // 5
-    type L = StrLen<"hello">;
-    ```
+// "people"
+const people = pluralize("person");
+```
 
-3. Concatenate strings:
+> **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.
 
-    ```ts
-    // "Hello world"
-    type C = Concat<["Hello ", "world"]>;
-    // "one, two, three"
-    type J = Join<["one", "two", "three"], ", ">;
-    ```
+#### Consistency with Ensure/Strip utilities
 
-4. Repeat a character a given number of times:
+- 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
-    // "1111"
-    type N = Repeat<"1", 4>;
-    ```
+  ```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
 
@@ -88,44 +120,14 @@ Below you'll find a cursory set of examples of both _type_ and _runtime_ utiliti
      type N = WithoutValue<Obj, string>;
      ```
 
-## Runtime Utilities
-
-### String Literals
-
-Many runtime utilities matchup well to their _type utility_ siblings. A good case in point is in converting a variable to a standardized naming convention. Whereas the type utility only changes the type, the runtime utility will ensure both runtime value and type are changed:
-
-```ts
-import { toCamelCase, toSnakeCase } from "inferred-types";
-
-// "camelCase"
-const camel = toCamelCase("camel-case");
-// "snake_case"
-const snake = toSnakeCase("snake-case");
-```
-
-You can also leverage the `pluralize()` function to change a variable to the plural version of the word (type and runtime value):
+## Contributing
 
-```ts
-// "people"
-const people = pluralize("person");
-```
+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.
 
-Also the common operations of `split` and `join` are supported as well:
+See the plentiful examples that exist under the `tests/` folder for inspiration.
 
-```ts
-// ["one","two","three"]
-const parts = split("one, two, three", ", ");
-// "one, two, three"
-const joined = join(parts, ", ");
-```
+**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.
 
-You can also ensure that a given string _is_ or _is not_ included in a string literal:
+## Licensing
 
-```ts
-// "bar"
-const bar = stripLeading("foobar", "foo");
-const bar2 = stripLeading("bar", "foo");
-// "foobar"
-const foobar = ensureLeading("bar", "foo");
-const foobar2 = ensureLeading("foobar", "foo");
-```
+This repo is offered under the highly permissive MIT license.