@orkestrel/contract 0.0.1

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

@@ -0,0 +1,112 @@
+import type { FieldPath, JSONSchema, RandomFunction, Result } from './types.js';
+/**
+ * Invoke a callback and capture its outcome as a {@link Result}, never letting
+ * a throw escape.
+ *
+ * @remarks
+ * The single sanctioned never-throw boundary for the guards (AGENTS §14). The
+ * `whereOf`, `lazyOf`, and `transformOf` combinators invoke caller-supplied
+ * callbacks *inside* a guard body, yet a guard must NEVER throw — it returns a
+ * `boolean`. This converts a throwing callback into a `Failure` so the
+ * surrounding guard can treat it as a non-match instead of propagating the
+ * exception, written once and shared rather than copy-pasted as ad-hoc
+ * `try`/`catch`.
+ *
+ * @param callback - The callback to invoke with no arguments
+ * @returns A `Success` carrying the return value, or a `Failure` carrying the
+ *          thrown reason normalised to an `Error`
+ *
+ * @example
+ * ```ts
+ * const outcome = attempt(() => predicate(value))
+ * return outcome.success && outcome.value
+ * ```
+ */
+export declare function attempt<T>(callback: () => T): Result<T>;
+/**
+ * Resolve a (possibly nested) field value from a record by a key or key path.
+ *
+ * @remarks
+ * A single `string` is ONE key (never split on `.`, so dotted keys are safe); a
+ * string array descends left-to-right through nested objects. Intermediates may
+ * be any object — records, class instances, or arrays indexed by string. Returns
+ * `undefined` the moment a segment is missing or lands on a non-object, so the
+ * lookup is total — even against a hostile getter or Proxy trap that throws on
+ * read, contained via {@link attempt} so the throw never escapes.
+ *
+ * @param record - The source record
+ * @param path - A property key, or a key path descending into nested objects
+ * @returns The resolved value, or `undefined`
+ *
+ * @example
+ * ```ts
+ * resolveField({ user: { name: 'Ada' } }, ['user', 'name']) // 'Ada'
+ * resolveField({ 'a.b': 1 }, 'a.b')                          // 1 (one key)
+ * resolveField({ a: 1 }, ['a', 'b'])                         // undefined
+ * ```
+ */
+export declare function resolveField(record: Readonly<Record<string, unknown>>, path: FieldPath): unknown;
+/**
+ * Build a deterministic pseudo-random source seeded from a single number.
+ *
+ * @remarks
+ * A mulberry32 generator — the same seed always yields the same sequence, so
+ * generated seed data is reproducible across runs. Used as the default random
+ * source for {@link compileGenerator}, seeded from the wall clock so casual
+ * callers still get varied output without passing a source themselves.
+ *
+ * @param seed - The seed for the sequence
+ * @returns A {@link RandomFunction} returning values in `[0, 1)`
+ *
+ * @example
+ * ```ts
+ * const random = seededRandom(42)
+ * random() // always the same first value for seed 42
+ * ```
+ */
+export declare function seededRandom(seed: number): RandomFunction;
+/**
+ * Count the enumerable own-symbol keys on a value.
+ *
+ * @remarks
+ * String keys are ignored — only `Object.getOwnPropertySymbols` entries whose
+ * descriptor is `enumerable` are counted. Backs the object-emptiness guards
+ * (`isEmptyObject` / `isNonEmptyObject`) so a record keyed only by an
+ * enumerable symbol is not mistaken for empty.
+ *
+ * @param value - The object to inspect
+ * @returns The number of enumerable own-symbol keys
+ *
+ * @example
+ * ```ts
+ * const flag = Symbol('flag')
+ * enumerableSymbolCount(Object.defineProperty({}, flag, { value: 1, enumerable: true })) // 1
+ * enumerableSymbolCount({}) // 0
+ * ```
+ */
+export declare function enumerableSymbolCount(value: object): number;
+/**
+ * Narrow a compiled {@link JSONSchema} down to the open `Readonly<Record<string, unknown>>` shape
+ * tool definitions advertise as `parameters` — through the {@link isRecord} boundary guard, never
+ * an assertion (AGENTS §14).
+ *
+ * @remarks
+ * A `JSONSchema` is the closed contract-compiler fragment (it has no index signature), whereas a
+ * tool advertises its `parameters` as an open record. The two are structurally compatible but not
+ * assignable, so the schema crosses that boundary through `isRecord` — a compiled contract schema
+ * is always a record, so the guard passes; the `undefined` fallback only satisfies the type's
+ * optionality. This is the single sanctioned narrowing from a compiled contract schema to the open
+ * tool-parameters record, so the crossing lives once rather than being copy-pasted per call site.
+ *
+ * @param schema - The compiled JSON Schema (a contract's `schema`)
+ * @returns The schema as the open tool-parameters record, or `undefined` when it is not a record
+ *
+ * @example
+ * ```ts
+ * import { createContract, schemaToParameters } from '@src/core'
+ *
+ * const contract = createContract(shape)
+ * const parameters = schemaToParameters(contract.schema) // the open record a tool advertises
+ * ```
+ */
+export declare function schemaToParameters(schema: JSONSchema): Readonly<Record<string, unknown>> | undefined;

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

@@ -0,0 +1,8 @@
+export type * from './types.js';
+export * from './constants.js';
+export * from './helpers.js';
+export * from './combinators.js';
+export * from './compilers.js';
+export * from './parsers.js';
+export * from './shapers.js';
+export * from './validators.js';