inferred-types 0.36.4 → 0.37.1

package/README.md

@@ -1,5 +1,5 @@
 # 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-type** type utilities.
+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.
 
 All utilities are tested for runtime and design-time correctness.

package/package.json

@@ -1,25 +1,30 @@
 {
   "name": "inferred-types",
-  "version": "0.36.4",
+  "version": "0.37.1",
   "description": "Functions which provide useful type inference on TS projects",
   "license": "MIT",
   "author": "Ken Snyder<ken@ken.net>",
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
-  "typings": "dist/index.d.ts",
+  "module": "./dist/index.js",
+  "typings": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
   "repository": {
     "url": "https://github.com/inocan-group/inferred-types"
   },
   "sideEffects": false,
   "scripts": {
     "about": "tokei src",
-    "autoindex": "npx dd autoindex",
-    "build": "run-s clean autoindex lint build:bundle",
-    "build:force": "run-s clean autoindex build:bundle",
-    "build:bundle": "npx tsup src/index.ts --dts --format=esm --clean",
+    "build": "run-s lint build:bundle",
+    "build:bundle": "tsup src/index.ts --dts --format=esm --clean",
     "watch": "run-p watch:*",
-    "watch:autoindex": "npx dd autoindex --watch",
-    "watch:bundle": "npx tsup src/index.ts --dts --format=esm --watch",
+    "watch:bundle": "tsup src/index.ts --dts --format=esm --watch",
     "clean": "rimraf dist/**/*",
     "lint": "eslint src/**/*.ts --fix && tsc --noEmit ",
     "lint:full": "eslint src/**/*.ts && eslint tests/**/*.ts && tsc --noEmit",
@@ -38,10 +43,7 @@
     "@typescript-eslint/parser": "^5.46.0",
     "@vitest/ui": "^0.25.6",
     "bumpp": "^8.2.1",
-    "common-types": "^1.33.2",
     "cross-env": "^7.0.3",
-    "dd": "^0.25.4",
-    "dotenv": "^16.0.3",
     "eslint": "^8.29.0",
     "eslint-config-prettier": "^8.5.0",
     "eslint-plugin-import": "^2.26.0",
@@ -50,8 +52,6 @@
     "npm-run-all": "~4.1.5",
     "pathe": "^1.0.0",
     "prettier": "~2.8.1",
-    "rimraf": "^3.0.2",
-    "sharp": "^0.31.2",
     "tsup": "^6.5.0",
     "typescript": "^4.9.4",
     "vite": "^3.2.5",
@@ -59,11 +59,5 @@
   },
   "dependencies": {
     "brilliant-errors": "^0.7.1"
-  },
-  "pnpm": {
-    "overrides": {
-      "simple-git@<3.3.0": ">=3.3.0",
-      "simple-git@<3.5.0": ">=3.5.0"
-    }
   }
 }

package/.eslintrc

@@ -1,77 +0,0 @@
-{
-  "extends": [
-    "plugin:import/warnings",
-    "plugin:import/typescript"
-  ],
-  "plugins": [
-    "@typescript-eslint",
-    "import",
-    "promise"
-  ],
-  "parser": "@typescript-eslint/parser",
-  "parserOptions": {
-    "parser": "@typescript-eslint/parser",
-    "sourceType": "module",
-    "ecmaVersion": 12
-  },
-  "rules": {
-    "prefer-const": "error",
-    "semi": [
-      "error",
-      "always"
-    ],
-    "quotes": [
-      "warn",
-      "double",
-      {
-        "avoidEscape": true,
-        "allowTemplateLiterals": true
-      }
-    ],
-    "no-unused-vars": "off",
-    "curly": "error",
-    "brace-style": [
-      "error",
-      "1tbs",
-      {
-        "allowSingleLine": true
-      }
-    ],
-    "no-nested-ternary": "off",
-    // we need exceptions to be only "warn" because
-    // there are valid use cases for generic variables being
-    // used before being defined
-    "no-use-before-define": [
-      "warn"
-    ],
-    "@typescript-eslint/semi": [
-      "error",
-      "always"
-    ],
-    "@typescript-eslint/no-unsafe-member-access": "off",
-    "@typescript-eslint/no-unsafe-call": "off",
-    "@typescript-eslint/no-unsafe-assignment": "off",
-    "@typescript-eslint/member-delimiter-style": [
-      "error",
-      {
-        "multiline": {
-          "delimiter": "semi",
-          "requireLast": true
-        },
-        "singleline": {
-          "delimiter": "semi",
-          "requireLast": false
-        }
-      }
-    ],
-    // "cases" allows for graceful use of that variable
-    // name in Typescript test cases
-    "@typescript-eslint/no-unused-vars": [
-      "error",
-      {
-        "varsIgnorePattern": "cases|^_",
-        "argsIgnorePattern": "^_"
-      }
-    ]
-  }
-}

package/.github/workflows/main.yml

@@ -1,34 +0,0 @@
-name: Continuous Integration
-
-on:
-  push:
-    branches:
-      - main
-      - master
-
-jobs:
-  testing:
-    name: testing
-    uses: yankeeinlondon/gha/.github/workflows/test.yml@main
-
-  publish:
-    name: npm
-    if: ( contains(github.event.head_commit.message, 'release v') )
-    needs:
-      - testing
-    uses: yankeeinlondon/gha/.github/workflows/npm.yml@main
-    with:
-      nodeVersion: 16
-    secrets:
-      npm_token: ${{secrets.NPM_TOKEN}}
-
-  do_not_publish:
-    name: npm / no publication
-    if: ( !contains(github.event.head_commit.message, 'release v') )
-    runs-on: ubuntu-latest
-    needs:
-      - testing
-    steps:
-      - name: Done
-        run: |
-          echo "::notice ::No need to publish to NPM"

package/.github/workflows/other.yml

@@ -1,15 +0,0 @@
-name: CI (features & PRs)
-
-on:
-  push:
-    branches:
-      - feature/*
-
-  pull_request:
-    branches:
-      - main
-      - master
-
-jobs:
-  testing:
-    uses: yankeeinlondon/gha/.github/workflows/test.yml@main

package/.nvmrc

@@ -1 +0,0 @@
-v14.15.3

package/.prettierrc.js

@@ -1,3 +0,0 @@
-module.exports = {
-  printWidth: 100,
-};

package/.vscode/launch.json

@@ -1,27 +0,0 @@
-{
-  "version": "0.2.0",
-  "configurations": [
-    {
-      "name": "Debug Jest Tests",
-      "type": "node",
-      "request": "launch",
-      "runtimeArgs": ["--inspect-brk", "${workspaceRoot}/node_modules/.bin/jest", "--runInBand"],
-      "console": "integratedTerminal",
-      "internalConsoleOptions": "neverOpen",
-      "port": 9229
-    },
-    {
-      "type": "node",
-      "request": "launch",
-      "name": "Jest Current File",
-      "program": "${workspaceFolder}/node_modules/.bin/jest",
-      "args": ["${fileBasenameNoExtension}", "--config", "jest.config.js"],
-      "console": "integratedTerminal",
-      "internalConsoleOptions": "neverOpen",
-      "disableOptimisticBPs": true,
-      "windows": {
-        "program": "${workspaceFolder}/node_modules/jest/bin/jest"
-      }
-    }
-  ]
-}

package/.vscode/settings.json

@@ -1,19 +0,0 @@
-{
-  "git.ignoreLimitWarning": true,
-  "editor.formatOnSave": true,
-  "cSpell.words": [
-    "Aint",
-    "appr",
-    "barbar",
-    "combinators",
-    "Dasherize",
-    "dasherized",
-    "Decomp",
-    "foey",
-    "foofoo",
-    "fooy",
-    "ruleset",
-    "tokei",
-    "Uncapitalize"
-  ]
-}

package/devops/build.js

@@ -1,243 +0,0 @@
-/* eslint-disable import/order */
-/* eslint-disable @typescript-eslint/no-var-requires */
-const rollup = require("rollup");
-const commonjs = require("@rollup/plugin-commonjs");
-const resolve = require("@rollup/plugin-node-resolve").default;
-const terser = require("rollup-plugin-terser").terser;
-const pkg = require("../package.json");
-const { builtinModules } = require("module");
-const analyze = require("rollup-plugin-analyzer");
-const typescript = require("rollup-plugin-typescript2");
-const closure = require("@ampproject/rollup-plugin-closure-compiler");
-const { existsSync, statSync } = require("fs");
-const { exit } = require("process");
-const { join } = require("path");
-
-const moduleSystems = process.argv.slice(2).filter((i) => !i.startsWith("-"));
-const switches = new Set(
-  process.argv
-    .slice(2)
-    .filter((i) => i.startsWith("-"))
-    .map((i) => i.replace(/^-(-){0,1}/, ""))
-);
-
-// makes all non-core deps external; allowing consuming app to gain better reuse
-const external = [
-  ...(pkg.peerDependencies ? Object.keys(pkg.peerDependencies) : []),
-  ...(pkg.optionalDependencies ? Object.keys(pkg.optionalDependencies) : []),
-  ...builtinModules,
-].map((i) => i.replace("@types/", ""));
-
-// required for IIFE and UMD modules
-const globals = {};
-
-function getFilenameByModule(mod) {
-  const shortname = getModuleShortname(mod);
-  const outputFile = {
-    es: pkg.module,
-    cjs: pkg.main,
-    typings: pkg.typings || pkg.types,
-  };
-
-  return Object.keys(outputFile).includes(shortname) && outputFile[shortname]
-    ? outputFile[shortname]
-    : `dist/${shortname}/index.js`;
-}
-
-/**
- * Reduce ES and CJS targets to just `es` and `cjs`
- *
- * @param {string} mod
- */
-function getModuleShortname(mod) {
-  const lowered = mod.toLowerCase();
-  return lowered.startsWith("es")
-    ? "es"
-    : lowered.startsWith("commonjs")
-    ? "cjs"
-    : mod.toLowerCase();
-}
-
-function inferDirectory(file) {
-  if (!file) {
-    return "";
-  }
-  const fileParts = file.split("/");
-  return fileParts.slice(0, fileParts.length - 1).join("/");
-}
-
-/**
- * create Rollup configuration
- *
- * @param {string} moduleSystem
- * @param {string} file
- * @param {boolean} minimized
- * @param {boolean} emitDeclaration
- */
-const moduleConfig = (moduleSystem, file, minimized, emitDeclaration) => {
-  try {
-    const input = "src/index.ts";
-    if (!existsSync(input)) {
-      console.log(`The source entry point was set as "${input}" but this was not found!`);
-      console.log();
-      exit(1);
-    }
-    const outDir = inferDirectory(file);
-    const declarationDir = pkg.typings ? inferDirectory(pkg.typings) : `dist/types`;
-    console.log(
-      `- the source's entrypoint is "${input}" and output will be put in "${outDir}" folder`
-    );
-    if (emitDeclaration) {
-      console.log(
-        `- the typings will also be generated and placed in the "${declarationDir}" directory`
-      );
-    }
-    const tsconfigOverride = {
-      compilerOptions: {
-        ...(emitDeclaration ? { declaration: emitDeclaration, declarationDir } : {}),
-        outDir,
-        module: "esnext",
-      },
-      exclude: ["test", "tests", "node_modules"],
-    };
-
-    return {
-      input,
-      external,
-      plugins: [
-        commonjs(),
-        resolve(),
-        typescript({
-          tsconfig: "tsconfig.json",
-          useTsconfigDeclarationDir: true,
-          tsconfigOverride,
-        }),
-
-        ...(getModuleShortname(moduleSystem) === "es" && (process.env.ANALYZE || switches.analyze)
-          ? [analyze()]
-          : []),
-        ...(switches.has("closure") ? [closure()] : []),
-        ...(switches.has("minimize") ? [terser()] : []),
-      ],
-    };
-  } catch (e) {
-    console.warn(`- 👎 the build failed building Rollup configuration: ${e.message}`);
-    console.log(`\n${e.stack}\n`);
-    process.exit(1);
-  }
-};
-
-/**
- * Takes a path and filename and adds `.min` before the filename's extension.
- *
- * @param {string} filename
- * @param {boolean} isMin
- */
-function minimizeFilename(filename, isMin) {
-  if (isMin) {
-    const parts = filename.split(".");
-    filename = join(parts.slice(0, parts.length - 1).join("."), `.min.${parts.slice(-1)}`);
-  }
-
-  return filename;
-}
-
-/**
- * Uses Rollup API to bundle the repo.
- *
- * @param {string} m
- * @param {boolean} min
- * @param {boolean} emitDeclaration
- */
-async function buildModule(m, min, emitDeclaration) {
-  try {
-    console.log(`- 📦 starting bundling of ${m.toUpperCase()} module ${min ? "(minimized)" : ""}`);
-    if (switches.has("closure")) {
-      console.log(`- using closure compiler to minimize file size`);
-    }
-    if (getModuleShortname(m) === "es" && !pkg.module) {
-      console.log(
-        `- 🤨 while you are building for the ES module system your package.json doesn't specify a "module" entrypoint.`
-      );
-    }
-    const file = minimizeFilename(getFilenameByModule(m), min);
-    console.log(`- transpiled source will be saved as: ${file}`);
-    // build the configuration
-    const config = moduleConfig(m, file, min, emitDeclaration);
-    if (switches.has("v") || switches.has("verbose")) {
-      console.log("- bundle config is:\n", JSON.stringify(config, null, 2));
-    }
-    const bundle = await rollup.rollup(config);
-
-    await bundle.write({
-      ...(usesGlobalVars(m) ? { name: pkg.name.replace(/-/g, ""), globals } : {}),
-      file,
-      format: getModuleShortname(m).startsWith("es") ? "es" : m,
-      exports: "auto",
-      sourcemap: false,
-    });
-    const output = statSync(file);
-    console.log(
-      `- 🚀 bundling saved to the "${file}" file [ ${Math.floor(output.size / 100) / 10} kb ].\n`
-    );
-  } catch (e) {
-    console.warn(`- 👎 the build failed during Rollup bundling`);
-    console.log(`\n${e.stack}\n`);
-    process.exit(1);
-  }
-}
-
-const usesGlobalVars = (mod) => {
-  return ["umd", "iife"].includes(mod);
-};
-
-(async () => {
-  const validModules = ["esnext", "es2020", "es2015", "commonjs", "iife", "umd"];
-  const hasValidModules = moduleSystems.every((m) => validModules.includes(m));
-  if (!hasValidModules) {
-    console.log(
-      `You specified an invalid module system. Valid module systems are: ${validModules.join(
-        ", "
-      )}; and you specified: ${moduleSystems.join(", ")}!\n`
-    );
-    process.exit(0);
-  }
-
-  console.log(
-    `- Building library to ${moduleSystems.map((m) => m.toUpperCase()).join(", ")} modules.`
-  );
-  const relevantModules = external.filter((i) => !builtinModules.includes(i));
-
-  if (Object.keys(relevantModules).length > 0) {
-    console.log(
-      `- While bundling will configure the following to be "external modules": ${relevantModules.join(
-        ", "
-      )}`
-    );
-  }
-  if (moduleSystems.includes("iife") || moduleSystems.includes("umd")) {
-    console.log(
-      `- The IIFE and UMD modules will link to global scope:\n\t${Object.keys(globals)
-        .map((g) => `- "${g}" module found in global scope as "${globals[g]}"\n\t`)
-        .join("")}`
-    );
-  }
-  console.log();
-
-  for (const m of moduleSystems) {
-    const emitDeclaration = moduleSystems.length === 1 || getModuleShortname(m) === "es";
-    await buildModule(m, false, emitDeclaration);
-  }
-
-  if (switches.has("min")) {
-    if (!moduleSystems.includes("commonjs")) {
-      throw new Error(
-        "Minimization was requested but no CJS module was built; either include CJS module build or remove minimization"
-      );
-    }
-    console.log("Building minimized version of CJS module system");
-    await buildModule("commonjs", true);
-  }
-
-  console.log("\n- Build completed!\n");
-})();

package/docs/builder-overview.md

@@ -1,45 +0,0 @@
-## Builder API States
-
-### Mutation Identity Functions
-
-Initially the user defines the API, to do this they need a reference to _state_ prior to it actually being set. This is achieved with a higher order function called a `MutationIdentity`:
-
-// f(a) => a
-// a === a + 0
-// a === a * 1
-
-```ts
-type State = { foo: number, bar: number };
-const f1 = (s: State) => (addToFoo: number) => { ...s, foo: s.foo + addToFoo };
-```
-
-### Identity API
-
-Ultimately functions like the one above are brought together into a dictionary to form a `MutationIdentityApi`. This is passed into the **Builder** along type a _type-guard_ which validates when configuration can be considered "done".
-
-```ts
-const api = { ...f1, ...f2 };
-const validation = (state: unknown): state is State {...};
-const b = Builder(api, validation, {});
-```
-
-### Mutation API
-
-The builder converts the dictionary mutation identity function into mutation functions. So, the `f1` function we defined earlier exposes a function that looks like this:
-
-```ts
-f1: (addToFoo: number) => { ...s, foo: s.foo + addToFoo };
-```
-
-this is a first step but can't be exposed as a builder as it returns _state_ rather than the same fluent API.
-
-### Fluent API Proxy
-
-The builder instead, wraps this function into a proxy which allows calls that the user makes to this into Fluent API:
-
-```ts
-const fluentApi: FluentApi<MutationApi> = {
-  f1: (addToFoo: number) => FluentApi<MutationApi>,
-  f2: () => FleuntApi<MutationApi>
-}
-```

package/docs/builder.md

@@ -1,94 +0,0 @@
-# Builder
-
-Aim is to pass in an API and a _target_ state and let the `Builder()` function manage the process. This includes:
-
-1. Allowing the API to indicate which API endpoints can only be called once
-2. Indicate when the configuration has reached a "completed" state (aka, there may be _more_ config you **can** do but no more that is **required**)
-
-
-## Key Builder States
-
-A builder's primary responsibility is about building up a _target state_ **`TS`** from an _initial state_ **`IS`**. 
-
-- The consumer of the builder must explicitly state **`TS`** as part of initialization
-
-    ```ts
-    type TS = { foo: number, bar: number, baz?: string };
-    const config = Builder<TS>(api, { foo:0, bar: 0 });
-    ```
-
-- The _initial state_ **`IS`** will automatically be assigned to `Partial<TS>`
-- The consumer's API should not mutate state directly but instead return a `Partial<TS>` representing the updated state.
-
-    ```ts
-    const api = ApiBuilder<TS>({
-        incFoo: (s) => () => {
-            return { ...s, foo: foo++};
-        },
-        setBar: (s) => (bar: number) => {
-            return { ...s, bar };
-        }
-    });
-    ```
-
-- If the API wants to exclude _itself_ or other parts of the API to the caller after being called then a rather than returning `T` it would instead return a tuple: `[ [T], "col", "col2" ]`:
-
-    ```ts
-    const api = ApiBuilder<TS>({
-        name: (s) => (name: string) => {
-            return [ { ...s, name }, "name" ];
-        }
-    });
-    ```
-
-- The Builder will proxy requests to the API definition and when it gets the updated state, it will:
-  - validate whether this new state represents a _completed_ state **`CS`**
-    - If completed, the builder returns `Completed<Api<TS, E>>`
-    - If _not_ completed the builder returns `Api<TS, E>`
-  - in both cases:
-    - the API that the consumer gets back is the same fluent API surface
-    - the API is pruned from the column names in `E`
-  - the `Completed<Api<T>>` typing is used to act as a hint to the `Unwrap()` function
-- The `Unwrap()` function is designed to unwrap the state contained by the builder:
-
-    - if the API has been completed then **`TS`** will be returned
-    - if not then **`Partial<TS>`** will be returned
-
-
-## Interaction Diagram
-The below diagram is meant to represent the Key States flow described above:
-
-   ```mermaid
-   sequenceDiagram
-       participant App;
-       participant Builder;
-       participant API;
-
-       App->>App: create TS target STATE
-
-       
-       App->>Builder: configure Builder w/ API and initial STATE
-       activate Builder
-       Builder->>API: store API
-       activate API
-       API-->>Builder: 
-       deactivate API
-
-       Builder->>App: returns <TApi> proxy interface
-       deactivate Builder;
-
-
-       App->>Builder: call API
-       activate Builder
-       
-       Builder->>API: proxy through API req
-       activate API
-       API-->>API: mutate state
-       API->>Builder: response
-       deactivate API
-       Builder-->>Builder: validate whether completed
-       Builder->>App: return either <TApi> or Completed<TApi>
-       deactivate Builder
-   ```
-
-

package/src/errors/ReadOnlyViolation.ts

@@ -1,3 +0,0 @@
-import { createError } from "brilliant-errors";
-
-export default createError("read-only-violation", "inferred-types")()()()();

package/src/errors/index.ts

@@ -1,12 +0,0 @@
-// #autoindex
-// #region auto-indexed files
-// index last changed at: 8th Aug, 2022, 09:51 AM ( GMT-7 )
-// hash-code: 30d9ddb2
-
-// file exports
-export * from "./ReadOnlyViolation";
-
-// #endregion auto-indexed files
-
-// see https://github.com/inocan-group/do-devops/docs/autoindex.md
-// for more info

package/src/index.ts

@@ -1,14 +0,0 @@
-// #autoindex
-
-// #region auto-indexed files
-// index last changed at: 8th Aug, 2022, 09:51 AM ( GMT-7 )
-// hash-code: 5ddbbf55
-
-// directory exports
-export * from "./types/index";
-export * from "./runtime/index";
-
-// #endregion auto-indexed files
-
-// see https://github.com/inocan-group/do-devops/docs/autoindex.md
-// for more info

package/src/runtime/README.md

@@ -1,3 +0,0 @@
-# Helpers
-
-Small utility-belt functions which are exported directly (as well as potentially being used internally).