@orkestrel/contract 0.0.1

package/dist/src/core/validators.d.ts

@@ -0,0 +1,250 @@
+import type { AnyAsyncFunction, AnyConstructor, AnyFunction, JSONPrimitive, JSONValue, ZeroArgAsyncFunction, ZeroArgFunction } from './types.js';
+/** Determine whether a value is `null`. */
+export declare function isNull(value: unknown): value is null;
+/** Determine whether a value is `undefined`. */
+export declare function isUndefined(value: unknown): value is undefined;
+/** Determine whether a value is defined (neither `null` nor `undefined`). */
+export declare function isDefined<T>(value: T | null | undefined): value is T;
+/** Determine whether a value is a string. */
+export declare function isString(value: unknown): value is string;
+/**
+ * Determine whether a value is a number.
+ *
+ * @remarks
+ * Includes `NaN` and `±Infinity` — use {@link isFiniteNumber} to exclude them.
+ */
+export declare function isNumber(value: unknown): value is number;
+/** Determine whether a value is a finite number (excludes `NaN` and `±Infinity`). */
+export declare function isFiniteNumber(value: unknown): value is number;
+/** Determine whether a value is a finite integer (excludes `NaN`, `±Infinity`, and fractional numbers). */
+export declare function isInteger(value: unknown): value is number;
+/** Determine whether a value is a boolean. */
+export declare function isBoolean(value: unknown): value is boolean;
+/** Determine whether a value is exactly `true`. */
+export declare function isTrue(value: unknown): value is true;
+/** Determine whether a value is exactly `false`. */
+export declare function isFalse(value: unknown): value is false;
+/** Determine whether a value is a bigint. */
+export declare function isBigInt(value: unknown): value is bigint;
+/** Determine whether a value is a symbol. */
+export declare function isSymbol(value: unknown): value is symbol;
+/** Determine whether a value is callable. */
+export declare function isFunction(value: unknown): value is AnyFunction;
+/** Determine whether a value is a string or `null`. */
+export declare function isNullableString(value: unknown): value is string | null;
+/** Determine whether a value is a number or `null` (the number may be `NaN` / `±Infinity`). */
+export declare function isNullableNumber(value: unknown): value is number | null;
+/** Determine whether a value is a boolean or `null`. */
+export declare function isNullableBoolean(value: unknown): value is boolean | null;
+/** Determine whether a value is a `Date`. */
+export declare function isDate(value: unknown): value is Date;
+/** Determine whether a value is a `RegExp`. */
+export declare function isRegExp(value: unknown): value is RegExp;
+/** Determine whether a value is an `Error`. */
+export declare function isError(value: unknown): value is Error;
+/** Determine whether a value is a native `Promise` (use {@link isPromiseLike} for any thenable). */
+export declare function isPromise<T = unknown>(value: unknown): value is Promise<T>;
+/**
+ * Determine whether a value is promise-like — an object exposing callable
+ * `then`, `catch`, and `finally` methods.
+ *
+ * @remarks
+ * Accepts any object with all three methods, not only native `Promise`
+ * instances. Use {@link isPromise} when you specifically need `instanceof Promise`.
+ */
+export declare function isPromiseLike<T = unknown>(value: unknown): value is Promise<T> | (PromiseLike<T> & {
+    catch: unknown;
+    finally: unknown;
+});
+/** Determine whether a value is an `ArrayBuffer`. */
+export declare function isArrayBuffer(value: unknown): value is ArrayBuffer;
+/**
+ * Determine whether a value is a `SharedArrayBuffer`.
+ *
+ * @remarks
+ * Guards the global existence of `SharedArrayBuffer` first — safe where it is
+ * absent or disabled (e.g. a context that is not cross-origin isolated).
+ */
+export declare function isSharedArrayBuffer(value: unknown): value is SharedArrayBuffer;
+/**
+ * Determine whether a value implements the iterable protocol (`Symbol.iterator`).
+ *
+ * @remarks
+ * Strings are explicitly included: a string has a callable `Symbol.iterator`
+ * but is not an object, so the generic object path alone would miss it.
+ */
+export declare function isIterable<T = unknown>(value: unknown): value is Iterable<T>;
+/** Determine whether a value implements the async iterable protocol (`Symbol.asyncIterator`). */
+export declare function isAsyncIterable<T = unknown>(value: unknown): value is AsyncIterable<T>;
+/**
+ * Determine whether a value is a non-null object.
+ *
+ * @remarks
+ * `true` for arrays, class instances, plain objects, `Map`, `Set`, etc. — use
+ * {@link isRecord} when you need a plain-record check.
+ */
+export declare function isObject(value: unknown): value is object;
+/**
+ * Determine whether a value is a plain record (object literal or null-prototype),
+ * not an array or class instance.
+ *
+ * @remarks
+ * Use instead of {@link isObject} to distinguish a plain `{}` /
+ * `Object.create(null)` from arrays, `Date`, `Map`, etc. The prototype-chain
+ * test is realm-agnostic: rather than comparing against the current realm's
+ * `Object.prototype` (which a plain object from another `vm.Context`, iframe,
+ * or worker would fail), it accepts any value whose prototype is `null`, OR
+ * whose prototype's own prototype is `null` — the shape every plain object
+ * has in every realm, since `Object.prototype` itself always sits one step
+ * above `null`. Arrays and class instances are still rejected: an array's
+ * prototype chain runs through `Array.prototype` before `null`, and a class
+ * instance's runs through the class's own prototype. The whole body runs
+ * inside `attempt` (AGENTS §14) so a revoked `Proxy` or a hostile
+ * `getPrototypeOf` trap cannot escape as a thrown error.
+ */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Determine whether a value is a `Map`. */
+export declare function isMap<K = unknown, V = unknown>(value: unknown): value is ReadonlyMap<K, V>;
+/** Determine whether a value is a `Set`. */
+export declare function isSet<T = unknown>(value: unknown): value is ReadonlySet<T>;
+/** Determine whether a value is a `WeakMap`. */
+export declare function isWeakMap(value: unknown): value is WeakMap<object, unknown>;
+/** Determine whether a value is a `WeakSet`. */
+export declare function isWeakSet(value: unknown): value is WeakSet<object>;
+/** Determine whether a value is an array. */
+export declare function isArray<T = unknown>(value: unknown): value is readonly T[];
+/** Determine whether a value is a `DataView`. */
+export declare function isDataView(value: unknown): value is DataView<ArrayBufferLike>;
+/** Determine whether a value is an `ArrayBufferView` (any typed array or `DataView`). */
+export declare function isArrayBufferView(value: unknown): value is ArrayBufferView;
+/** Determine whether a value is an `Int8Array`. */
+export declare function isInt8Array(value: unknown): value is Int8Array;
+/** Determine whether a value is a `Uint8Array`. */
+export declare function isUint8Array(value: unknown): value is Uint8Array;
+/** Determine whether a value is a `Uint8ClampedArray`. */
+export declare function isUint8ClampedArray(value: unknown): value is Uint8ClampedArray;
+/** Determine whether a value is an `Int16Array`. */
+export declare function isInt16Array(value: unknown): value is Int16Array;
+/** Determine whether a value is a `Uint16Array`. */
+export declare function isUint16Array(value: unknown): value is Uint16Array;
+/** Determine whether a value is an `Int32Array`. */
+export declare function isInt32Array(value: unknown): value is Int32Array;
+/** Determine whether a value is a `Uint32Array`. */
+export declare function isUint32Array(value: unknown): value is Uint32Array;
+/** Determine whether a value is a `Float32Array`. */
+export declare function isFloat32Array(value: unknown): value is Float32Array;
+/** Determine whether a value is a `Float64Array`. */
+export declare function isFloat64Array(value: unknown): value is Float64Array;
+/**
+ * Determine whether a value is a `BigInt64Array`.
+ *
+ * @remarks
+ * Guards the global existence of `BigInt64Array` first — safe in environments
+ * that pre-date the BigInt typed-array additions.
+ */
+export declare function isBigInt64Array(value: unknown): value is BigInt64Array;
+/**
+ * Determine whether a value is a `BigUint64Array`.
+ *
+ * @remarks
+ * Guards the global existence of `BigUint64Array` first — safe in environments
+ * that pre-date the BigInt typed-array additions.
+ */
+export declare function isBigUint64Array(value: unknown): value is BigUint64Array;
+/** Determine whether a value is the empty string `''`. */
+export declare function isEmptyString(value: unknown): value is '';
+/** Determine whether a value is an empty array. */
+export declare function isEmptyArray(value: unknown): value is readonly [];
+/** Determine whether a value is an empty plain object (no own string or enumerable symbol keys). */
+export declare function isEmptyObject(value: unknown): value is Record<string | symbol, never>;
+/** Determine whether a value is an empty `Map`. */
+export declare function isEmptyMap(value: unknown): value is ReadonlyMap<never, never>;
+/** Determine whether a value is an empty `Set`. */
+export declare function isEmptySet(value: unknown): value is ReadonlySet<never>;
+/** Determine whether a value is a non-empty string (at least one character). */
+export declare function isNonEmptyString(value: unknown): value is string;
+/** Determine whether a value is a non-empty array (at least one element). */
+export declare function isNonEmptyArray<T = unknown>(value: unknown): value is readonly [T, ...T[]];
+/** Determine whether a value is a non-empty plain object (at least one own string or enumerable symbol key). */
+export declare function isNonEmptyObject(value: unknown): value is Record<string | symbol, unknown>;
+/** Determine whether a value is a non-empty `Map` (at least one entry). */
+export declare function isNonEmptyMap<K = unknown, V = unknown>(value: unknown): value is ReadonlyMap<K, V>;
+/** Determine whether a value is a non-empty `Set` (at least one element). */
+export declare function isNonEmptySet<T = unknown>(value: unknown): value is ReadonlySet<T>;
+/** Determine whether a value is a function that declares zero parameters (`Function.length === 0`). */
+export declare function isZeroArg(value: unknown): value is ZeroArgFunction;
+/**
+ * Determine whether a value is a native `async function`.
+ *
+ * @remarks
+ * Uses `constructor.name === 'AsyncFunction'` — not `instanceof`, which is
+ * unreliable across realms. The `?.` keeps the guard total (§14): a function
+ * whose `constructor` was nulled yields `undefined`, never a thrown `null.name`.
+ */
+export declare function isAsyncFunction(value: unknown): value is AnyAsyncFunction;
+/** Determine whether a value is a generator function (`function*`). */
+export declare function isGeneratorFunction(value: unknown): value is (...args: unknown[]) => Generator<unknown, unknown, unknown>;
+/** Determine whether a value is an async generator function (`async function*`). */
+export declare function isAsyncGeneratorFunction(value: unknown): value is (...args: unknown[]) => AsyncGenerator<unknown, unknown, unknown>;
+/** Determine whether a value is a zero-argument async function. */
+export declare function isZeroArgAsync(value: unknown): value is ZeroArgAsyncFunction;
+/** Determine whether a value is a zero-argument generator function. */
+export declare function isZeroArgGenerator(value: unknown): value is () => Generator<unknown, unknown, unknown>;
+/** Determine whether a value is a zero-argument async generator function. */
+export declare function isZeroArgAsyncGenerator(value: unknown): value is () => AsyncGenerator<unknown, unknown, unknown>;
+/**
+ * Determine whether a value can be used as a `new`-target constructor.
+ *
+ * @remarks
+ * Probes with `Reflect.construct(String, [], value)`: a real constructor
+ * succeeds, while arrow functions, plain functions, and non-functions throw
+ * and yield `false`. Never throws. Backs the `instanceOf` combinator.
+ */
+export declare function isConstructor(value: unknown): value is AnyConstructor<object>;
+/**
+ * Determine whether a value is a cycle-safe JSON value.
+ *
+ * @remarks
+ * Total guard: never throws, returns `false` for cycles, functions, `Date`
+ * instances, class instances, `NaN`, and `±Infinity`. Arrays and plain records
+ * are walked with an ancestor set so recursive input fails instead of hanging.
+ * The whole walk runs inside `attempt` (AGENTS §14): a hostile getter on a
+ * record property, or a revoked `Proxy` anywhere in the structure, is caught
+ * and yields `false` instead of escaping as a thrown error.
+ *
+ * @param value - The value to test
+ * @returns `true` when the value has a JSON representation
+ *
+ * @example
+ * ```ts
+ * isJSONValue({ nested: [1, 'x', null] }) // true
+ * isJSONValue(Number.NaN)                 // false
+ * ```
+ */
+export declare function isJSONValue(value: unknown): value is JSONValue;
+/**
+ * Determine whether a value is a primitive JSON value.
+ *
+ * @remarks
+ * The flat leaf of any JSON document: `null`, a string, a **finite** number, or
+ * a boolean. Uses {@link isFiniteNumber} (not {@link isNumber}) because real JSON
+ * carries no `NaN` / `±Infinity` — `JSON.stringify(NaN)` is `'null'`.
+ *
+ * The recursive {@link isJSONValue} guard is shipped and stays total with
+ * cycle-safe walking. Dedicated `isJSONObject` / `isJSONSchema` validators and
+ * the broad `JSONSchemaDefinition` remain omitted; compose narrower shapes with
+ * the combinators and gate untrusted strings with `parseJSON` / `parseJSONAs`.
+ *
+ * @param value - The value to test
+ * @returns `true` when `value` is `null`, a string, a finite number, or a boolean
+ *
+ * @example
+ * ```ts
+ * isJSONPrimitive(null)        // true
+ * isJSONPrimitive('hi')        // true
+ * isJSONPrimitive(42)          // true
+ * isJSONPrimitive(Number.NaN)  // false — not representable in JSON
+ * isJSONPrimitive({})          // false
+ * ```
+ */
+export declare function isJSONPrimitive(value: unknown): value is JSONPrimitive;

package/package.json

@@ -0,0 +1,69 @@
+{
+	"name": "@orkestrel/contract",
+	"version": "0.0.1",
+	"description": "Zero-dependency contract toolkit — type guards, combinators, parsers, and a shape DSL that compiles one contract shape into a guard, parser, JSON Schema, and generator. The foundation package of the @orkestrel line.",
+	"keywords": [
+		"contracts",
+		"json-schema",
+		"parsers",
+		"type-guards",
+		"typescript",
+		"validation",
+		"zero-dependency"
+	],
+	"homepage": "https://github.com/orkestrel/contract#readme",
+	"bugs": "https://github.com/orkestrel/contract/issues",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/orkestrel/contract.git"
+	},
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"type": "module",
+	"sideEffects": false,
+	"main": "./dist/src/core/index.js",
+	"types": "./dist/src/core/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/src/core/index.d.ts",
+			"import": "./dist/src/core/index.js",
+			"default": "./dist/src/core/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"clean": "node -e \"try{require('node:fs').rmSync('dist',{recursive:true,force:true})}catch{}\"",
+		"copy": "node -e \"const fs=require('node:fs'),p=require('node:path'),a=process.argv[1],b=process.argv[2];fs.mkdirSync(p.dirname(b),{recursive:true});fs.cpSync(a,b,{force:true});console.log('Copied: '+a+' to '+b)\"",
+		"tmp:txt": "node -e \"const fs=require('node:fs'),p=require('node:path');function walk(d){for(const e of fs.readdirSync(d,{withFileTypes:true})){const f=p.join(d,e.name);if(e.isDirectory()){walk(f)}else if(!e.name.endsWith('.md')&&!e.name.endsWith('.txt')){const t=f+'.txt';if(!fs.existsSync(t)){fs.renameSync(f,t)}else{console.warn('Skipping '+f+' — target exists: '+t)}}}}try{walk('tmp')}catch(e){if(e.code!=='ENOENT')throw e}\"",
+		"lint": "oxlint --config .oxlintrc.json --fix .",
+		"check": "tsc --noEmit --project tsconfig.json",
+		"check:src": "npm run check:src:core",
+		"check:src:core": "tsc --noEmit -p configs/src/tsconfig.core.json",
+		"format": "oxfmt --config .oxfmtrc.json --write .",
+		"format:check": "oxfmt --config .oxfmtrc.json --check .",
+		"lint:check": "oxlint --config .oxlintrc.json .",
+		"test": "npm run test:src",
+		"test:src": "vitest run --config vite.config.ts --reporter=dot --project src:core",
+		"build": "npm run clean && npm run build:src",
+		"build:src": "npm run build:src:core",
+		"build:src:core": "vite build --config configs/src/vite.core.config.ts && tsc -p configs/src/tsconfig.core.json",
+		"prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run check:src && npm run build && npm test"
+	},
+	"devDependencies": {
+		"@types/node": "^26.1.1",
+		"oxfmt": "^0.58.0",
+		"oxlint": "^1.73.0",
+		"typescript": "^6.0.3",
+		"vite": "^8.1.4",
+		"vitest": "^4.1.10"
+	},
+	"engines": {
+		"node": ">=24"
+	}
+}