@klyper/types 0.3.0

package/README.md

@@ -0,0 +1,132 @@
+# @klyper/types
+
+Shared TypeScript type aliases and runtime type guards for Klyper packages.
+
+Use this package when a module needs small, dependency-free helpers for narrowing
+unknown values or reusing common utility types.
+
+## Installation
+
+```sh
+npm install @klyper/types
+```
+
+This package is published as an ES module package and also exposes a CommonJS
+entry through `main`.
+
+## Usage
+
+```ts
+import { isPlainObject, isString, type } from "@klyper/types";
+
+const value: unknown = { title: "Klyper" };
+
+if (isPlainObject(value) && isString(value.title)) {
+  value.title.toUpperCase();
+}
+
+type(value); // "object"
+```
+
+The runtime helpers accept `unknown` values and return TypeScript type predicates
+where possible.
+
+## Runtime API
+
+### Type detection
+
+| Export | Description |
+| --- | --- |
+| `type(value)` | Returns a normalized logical type name. `null` and `undefined` both return `"null"`. |
+
+Recognized logical type names include `"array"`, `"asyncfunction"`, `"bigint"`,
+`"boolean"`, `"date"`, `"error"`, `"function"`, `"map"`, `"null"`, `"number"`,
+`"object"`, `"promise"`, `"regexp"`, `"set"`, `"string"`, `"symbol"`,
+`"weakmap"`, and `"weakset"`.
+
+### Type guards
+
+| Export | Narrows to | Notes |
+| --- | --- | --- |
+| `isArray(value)` | `Array<any>` | Checks array values. |
+| `isAsyncFunction(value)` | `TypeAnyAsyncFunction` | Checks functions declared with `async`. |
+| `isBigInt(value)` | `bigint` | Checks bigint primitives. |
+| `isBoolean(value)` | `boolean` | Checks boolean primitives. |
+| `isConstructor(value)` | `TypeAnyConstructor` | Checks functions whose prototype constructor points back to the function. |
+| `isDate(value)` | `Date` | Checks `Date` instances. |
+| `isDef<T>(value)` | `T` | Returns `false` for `null` and `undefined`. |
+| `isError(value)` | `Error` | Checks `Error` instances. |
+| `isFiniteNumber(value)` | `number` | Checks finite number primitives. |
+| `isFloat(value)` | `number` | Checks finite numbers with a fractional part. |
+| `isFunction(value)` | `TypeAnyFunction` | Checks callable values. |
+| `isInteger(value)` | `number` | Checks integer number primitives. |
+| `isMap<K, V>(value)` | `Map<K, V>` | Checks `Map` instances. |
+| `isNil(value)` | `null \| undefined` | Checks only `null` and `undefined`. |
+| `isNonEmptyArray<T>(value)` | `[T, ...Array<T>]` | Checks arrays with at least one item. |
+| `isNull(value)` | `null` | Checks only `null`. |
+| `isNumber(value)` | `number` | Checks number primitives, including `NaN` and infinities. |
+| `isNumberLike(value)` | `boolean` | Checks strings that represent finite decimal numbers. Scientific, binary, hex, `NaN`, and `Infinity` strings are rejected. |
+| `isObject(value)` | `TypeAnyObject` | Checks values whose normalized logical type is `"object"`, including object literals, `Object.create(null)`, and class instances. Arrays, maps, sets, dates, and regexps are excluded. |
+| `isPlainObject(value)` | `TypeAnyObject` | Checks object literals and `Object.create(null)` values. Class instances are excluded. |
+| `isPromise<T>(value)` | `Promise<T>` | Checks `Promise` instances, not arbitrary thenables. |
+| `isRegExp(value)` | `RegExp` | Checks regular expressions. |
+| `isScalar(value)` | `TypeScalar` | Checks boolean, number, and string values. |
+| `isSet<T>(value)` | `Set<T>` | Checks `Set` instances. |
+| `isString(value)` | `string` | Checks string primitives. |
+| `isSymbol(value)` | `symbol` | Checks symbol primitives. |
+| `isUndefined(value)` | `undefined` | Checks only `undefined`. |
+
+## Type Aliases
+
+Common exported type aliases include:
+
+```ts
+import type {
+  TypeAnyAsyncFunction,
+  TypeAnyConstructor,
+  TypeAnyFunction,
+  TypeAnyObject,
+  TypeCallback,
+  TypeNullable,
+  TypeName,
+  TypeObjectOptional,
+  TypeObjectRequired,
+  TypeScalar,
+} from "@klyper/types";
+```
+
+Notable groups:
+
+- Array aliases: `TypeArray`, `TypeAnyArray`, `TypeFunctionArray`,
+  `TypeNumberArray`, `TypeObjectArray`, and `TypeStringArray`.
+- Object aliases: `TypeObject`, `TypeAnyObject`, `TypeBooleanObject`,
+  `TypeFunctionObject`, `TypeNumberObject`, and `TypeStringObject`.
+- Object shape helpers: `TypeObjectOptional`, `TypeObjectRequired`,
+  `TypeObjectKeys`, and `TypeObjectKeysFunction`.
+- Callback aliases: `TypeCallback`, `TypeCallbackArray`, `TypeCallbackMap`,
+  and `TypeCallbackObject`.
+- Value helpers: `TypeKey`, `TypeNullable`, `TypeOptional`, and `TypeScalar`.
+
+Primitive guards such as `isString`, `isNumber`, `isBoolean`, `isBigInt`, and
+`isSymbol` only accept primitives. Boxed wrappers such as `new String("x")`,
+`new Number(1)`, and `new Boolean(false)` return `false`.
+
+## Commands
+
+```sh
+npm run build --workspace @klyper/types
+npm run check --workspace @klyper/types
+npm run lint --workspace @klyper/types
+npm test --workspace @klyper/types
+```
+
+`build` uses Rollup for the package output. `check` runs TypeScript without emitting files.
+
+## Validation
+
+Run the package checks before publishing or changing exports:
+
+```sh
+npm run check --workspace @klyper/types
+npm test --workspace @klyper/types
+```

package/dist/index.cjs

@@ -0,0 +1,124 @@
+/*!
+ * @klyper/types v0.3.0
+ * Klyper types package.
+ * (c) 2026 Andrew Caires
+ * @license: MIT
+ */
+
+'use strict';
+
+const typeNames = {
+    "[object Array]": "array",
+    "[object AsyncFunction]": "asyncfunction",
+    "[object BigInt]": "bigint",
+    "[object Boolean]": "boolean",
+    "[object Date]": "date",
+    "[object Error]": "error",
+    "[object Function]": "function",
+    "[object Map]": "map",
+    "[object Number]": "number",
+    "[object Object]": "object",
+    "[object Promise]": "promise",
+    "[object RegExp]": "regexp",
+    "[object Set]": "set",
+    "[object String]": "string",
+    "[object Symbol]": "symbol",
+    "[object WeakMap]": "weakmap",
+    "[object WeakSet]": "weakset",
+};
+const type = (test) => {
+    if (test == null) {
+        return "null";
+    }
+    return typeNames[Object.prototype.toString.call(test)] ?? "object";
+};
+
+const isArray = (test) => type(test) == "array";
+
+const isAsyncFunction = (test) => type(test) == "asyncfunction";
+
+const isBigInt = (test) => typeof test == "bigint";
+
+const isBoolean = (test) => typeof test == "boolean";
+
+const isFunction = (test) => typeof test == "function";
+
+const isConstructor = (test) => isFunction(test) && !!test.prototype && test.prototype.constructor === test;
+
+const isDate = (test) => type(test) == "date";
+
+const isNil = (test) => test === null || test === undefined;
+
+const isDef = (test) => !isNil(test);
+
+const isError = (test) => type(test) == "error";
+
+const isFiniteNumber = (test) => Number.isFinite(test);
+
+const isFloat = (test) => isFiniteNumber(test) && !Number.isInteger(test);
+
+const isInteger = (test) => Number.isInteger(test);
+
+const isMap = (test) => type(test) == "map";
+
+const isNonEmptyArray = (test) => isArray(test) && test.length > 0;
+
+const isNull = (test) => test === null;
+
+const isNumber = (test) => typeof test == "number";
+
+const NUMBER_PATTERN = /^-?[0-9]+(\.[0-9]+)?$/;
+const isNumberLike = (value) => NUMBER_PATTERN.test(value);
+
+const isObject = (test) => type(test) == "object";
+
+const isPlainObject = (test) => {
+    if (!isObject(test) || type(test) != "object") {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(test);
+    return prototype === null || prototype === Object.prototype;
+};
+
+const isPromise = (test) => type(test) == "promise";
+
+const isRegExp = (test) => type(test) == "regexp";
+
+const isString = (test) => typeof test == "string";
+
+const isScalar = (test) => isBoolean(test) || isNumber(test) || isString(test);
+
+const isSet = (test) => type(test) == "set";
+
+const isSymbol = (test) => typeof test == "symbol";
+
+const isUndefined = (test) => test === undefined;
+
+exports.isArray = isArray;
+exports.isAsyncFunction = isAsyncFunction;
+exports.isBigInt = isBigInt;
+exports.isBoolean = isBoolean;
+exports.isConstructor = isConstructor;
+exports.isDate = isDate;
+exports.isDef = isDef;
+exports.isError = isError;
+exports.isFiniteNumber = isFiniteNumber;
+exports.isFloat = isFloat;
+exports.isFunction = isFunction;
+exports.isInteger = isInteger;
+exports.isMap = isMap;
+exports.isNil = isNil;
+exports.isNonEmptyArray = isNonEmptyArray;
+exports.isNull = isNull;
+exports.isNumber = isNumber;
+exports.isNumberLike = isNumberLike;
+exports.isObject = isObject;
+exports.isPlainObject = isPlainObject;
+exports.isPromise = isPromise;
+exports.isRegExp = isRegExp;
+exports.isScalar = isScalar;
+exports.isSet = isSet;
+exports.isString = isString;
+exports.isSymbol = isSymbol;
+exports.isUndefined = isUndefined;
+exports.type = type;

package/dist/index.d.ts

@@ -0,0 +1,104 @@
+/*!
+ * @klyper/types v0.3.0
+ * Klyper types package.
+ * (c) 2026 Andrew Caires
+ * @license: MIT
+ */
+
+declare const isArray: <T = unknown>(test: unknown) => test is Array<T>;
+
+type TypeAnyConstructor<T = any> = new (...args: Array<any>) => T;
+type TypeAnyAsyncFunction<T = any> = (...args: Array<any>) => Promise<T>;
+type TypeAnyFunction<T = any> = (...args: Array<any>) => T;
+type TypeArray<T> = Array<T>;
+type TypeAnyArray = TypeArray<any>;
+type TypeFunctionArray = TypeArray<TypeAnyFunction>;
+type TypeNumberArray = TypeArray<number>;
+type TypeObjectArray<T = any> = TypeArray<TypeObject<T>>;
+type TypeStringArray = TypeArray<string>;
+type TypeKey = number | string | symbol;
+type TypeNullable<T> = T | null;
+type TypeScalar = boolean | number | string;
+type TypeOptional<T> = T | null | undefined;
+type TypeObject<T, K extends keyof any = string> = Record<K, T>;
+type TypeAnyObject = TypeObject<any>;
+type TypeBooleanObject = TypeObject<boolean>;
+type TypeFunctionObject = TypeObject<TypeAnyFunction>;
+type TypeNumberObject = TypeObject<number>;
+type TypeStringObject = TypeObject<string>;
+type TypeObjectOptional<T, K extends keyof T = keyof T> = {
+    [P in keyof T as P extends K ? never : P]: T[P];
+} & {
+    [P in keyof T as P extends K ? P : never]?: T[P];
+};
+type TypeObjectRequired<T, K extends keyof T> = {
+    [P in K]-?: T[P];
+} & {
+    [P in Exclude<keyof T, K>]: T[P];
+};
+type TypeObjectKeys<T, F = any> = {
+    [K in keyof T]: T[K] extends F ? K : never;
+}[keyof T];
+type TypeObjectKeysFunction<T> = TypeObjectKeys<T, TypeAnyFunction>;
+type TypeCallback<T, K, O, R> = (value: T, key: K, object: O) => R;
+type TypeCallbackArray<T> = TypeCallback<T, number, TypeArray<T>, any>;
+type TypeCallbackMap<T> = TypeCallback<T, number, TypeArray<T>, T>;
+type TypeCallbackObject<T> = TypeCallback<T, string, TypeObject<T>, any>;
+
+declare const isAsyncFunction: (test: unknown) => test is TypeAnyAsyncFunction;
+
+declare const isBigInt: (test: unknown) => test is bigint;
+
+declare const isBoolean: (test: unknown) => test is boolean;
+
+declare const isConstructor: (test: unknown) => test is TypeAnyConstructor;
+
+declare const isDate: (test: unknown) => test is Date;
+
+declare const isDef: <T = unknown>(test: T | null | undefined) => test is T;
+
+declare const isError: (test: unknown) => test is Error;
+
+declare const isFiniteNumber: (test: unknown) => test is number;
+
+declare const isFloat: (test: unknown) => test is number;
+
+declare const isFunction: (test: unknown) => test is TypeAnyFunction;
+
+declare const isInteger: (test: unknown) => test is number;
+
+declare const isMap: <K = any, V = any>(test: unknown) => test is Map<K, V>;
+
+declare const isNil: (test: unknown) => test is null | undefined;
+
+declare const isNonEmptyArray: <T = unknown>(test: unknown) => test is [T, ...Array<T>];
+
+declare const isNull: (test: unknown) => test is null;
+
+declare const isNumber: (test: unknown) => test is number;
+
+declare const isNumberLike: (value: string) => boolean;
+
+declare const isObject: (test: unknown) => test is TypeAnyObject;
+
+declare const isPlainObject: (test: unknown) => test is TypeAnyObject;
+
+declare const isPromise: <T = unknown>(test: unknown) => test is Promise<T>;
+
+declare const isRegExp: (test: unknown) => test is RegExp;
+
+declare const isScalar: (test: unknown) => test is TypeScalar;
+
+declare const isSet: <T = any>(test: unknown) => test is Set<T>;
+
+declare const isString: (test: unknown) => test is string;
+
+declare const isSymbol: (test: unknown) => test is symbol;
+
+declare const isUndefined: (test: unknown) => test is undefined;
+
+type TypeName = "array" | "asyncfunction" | "bigint" | "boolean" | "date" | "error" | "function" | "map" | "null" | "number" | "object" | "promise" | "regexp" | "set" | "string" | "symbol" | "weakmap" | "weakset";
+declare const type: (test: unknown) => TypeName;
+
+export { isArray, isAsyncFunction, isBigInt, isBoolean, isConstructor, isDate, isDef, isError, isFiniteNumber, isFloat, isFunction, isInteger, isMap, isNil, isNonEmptyArray, isNull, isNumber, isNumberLike, isObject, isPlainObject, isPromise, isRegExp, isScalar, isSet, isString, isSymbol, isUndefined, type };
+export type { TypeAnyArray, TypeAnyAsyncFunction, TypeAnyConstructor, TypeAnyFunction, TypeAnyObject, TypeArray, TypeBooleanObject, TypeCallback, TypeCallbackArray, TypeCallbackMap, TypeCallbackObject, TypeFunctionArray, TypeFunctionObject, TypeKey, TypeName, TypeNullable, TypeNumberArray, TypeNumberObject, TypeObject, TypeObjectArray, TypeObjectKeys, TypeObjectKeysFunction, TypeObjectOptional, TypeObjectRequired, TypeOptional, TypeScalar, TypeStringArray, TypeStringObject };

package/dist/index.js

@@ -0,0 +1,95 @@
+/*!
+ * @klyper/types v0.3.0
+ * Klyper types package.
+ * (c) 2026 Andrew Caires
+ * @license: MIT
+ */
+
+const typeNames = {
+    "[object Array]": "array",
+    "[object AsyncFunction]": "asyncfunction",
+    "[object BigInt]": "bigint",
+    "[object Boolean]": "boolean",
+    "[object Date]": "date",
+    "[object Error]": "error",
+    "[object Function]": "function",
+    "[object Map]": "map",
+    "[object Number]": "number",
+    "[object Object]": "object",
+    "[object Promise]": "promise",
+    "[object RegExp]": "regexp",
+    "[object Set]": "set",
+    "[object String]": "string",
+    "[object Symbol]": "symbol",
+    "[object WeakMap]": "weakmap",
+    "[object WeakSet]": "weakset",
+};
+const type = (test) => {
+    if (test == null) {
+        return "null";
+    }
+    return typeNames[Object.prototype.toString.call(test)] ?? "object";
+};
+
+const isArray = (test) => type(test) == "array";
+
+const isAsyncFunction = (test) => type(test) == "asyncfunction";
+
+const isBigInt = (test) => typeof test == "bigint";
+
+const isBoolean = (test) => typeof test == "boolean";
+
+const isFunction = (test) => typeof test == "function";
+
+const isConstructor = (test) => isFunction(test) && !!test.prototype && test.prototype.constructor === test;
+
+const isDate = (test) => type(test) == "date";
+
+const isNil = (test) => test === null || test === undefined;
+
+const isDef = (test) => !isNil(test);
+
+const isError = (test) => type(test) == "error";
+
+const isFiniteNumber = (test) => Number.isFinite(test);
+
+const isFloat = (test) => isFiniteNumber(test) && !Number.isInteger(test);
+
+const isInteger = (test) => Number.isInteger(test);
+
+const isMap = (test) => type(test) == "map";
+
+const isNonEmptyArray = (test) => isArray(test) && test.length > 0;
+
+const isNull = (test) => test === null;
+
+const isNumber = (test) => typeof test == "number";
+
+const NUMBER_PATTERN = /^-?[0-9]+(\.[0-9]+)?$/;
+const isNumberLike = (value) => NUMBER_PATTERN.test(value);
+
+const isObject = (test) => type(test) == "object";
+
+const isPlainObject = (test) => {
+    if (!isObject(test) || type(test) != "object") {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(test);
+    return prototype === null || prototype === Object.prototype;
+};
+
+const isPromise = (test) => type(test) == "promise";
+
+const isRegExp = (test) => type(test) == "regexp";
+
+const isString = (test) => typeof test == "string";
+
+const isScalar = (test) => isBoolean(test) || isNumber(test) || isString(test);
+
+const isSet = (test) => type(test) == "set";
+
+const isSymbol = (test) => typeof test == "symbol";
+
+const isUndefined = (test) => test === undefined;
+
+export { isArray, isAsyncFunction, isBigInt, isBoolean, isConstructor, isDate, isDef, isError, isFiniteNumber, isFloat, isFunction, isInteger, isMap, isNil, isNonEmptyArray, isNull, isNumber, isNumberLike, isObject, isPlainObject, isPromise, isRegExp, isScalar, isSet, isString, isSymbol, isUndefined, type };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@klyper/types",
+  "version": "0.3.0",
+  "description": "Klyper types package.",
+  "author": "Andrew Caires",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andrewcaires/klyper.git"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "npm run clean && npm run check && npm run bundle",
+    "bundle": "rollup --bundleConfigAsCjs -c ../../rollup.config.js",
+    "check": "npm run lint && npm run typecheck",
+    "clean": "rm -rf dist",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "prepublishOnly": "npm run build && npm test",
+    "test": "node --import tsx --test \"src/**/*.test.ts\"",
+    "test:watch": "node --import tsx --test --watch \"src/**/*.test.ts\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}