@mionjs/run-types 0.8.7 → 0.8.10

package/src/createRunTypeFunctions.ts

@@ -0,0 +1,93 @@
+/* ########
+ * 2025 mion
+ * Author: Ma-jerez
+ * License: MIT
+ * The software is provided "as is", without warranty of any kind.
+ * ######## */
+
+import {JitFunctions} from './constants.functions.ts';
+import {ReceiveType} from '@deepkit/type';
+import {runType} from './createRunType.ts';
+import {RunTypeOptions} from './types.ts';
+import {
+    FromBinaryFn,
+    IsTypeFn,
+    JsonStringifyFn,
+    PrepareForJsonFn,
+    RestoreFromJsonFn,
+    ToBinaryFn,
+    ToCodeFn,
+    TypeErrorsFn,
+} from '@mionjs/core';
+import {BaseRunType} from './lib/baseRunTypes.ts';
+import {registerJitFunctionCompiler} from './lib/jitFnsRegistry.ts';
+
+// All these functions are async because they might need to compile the jit function first
+// At the moment they are compiled synchronously, but in the future they might be async
+// Also some the src code to compile or functionality of the JIT functions might be loaded dynamically
+// ie: mocking functionality is loaded only when mockTypeFn is called
+
+/** Returns a function that checks if the given value is of the specified type. */
+export async function createIsTypeFn<T>(opts?: RunTypeOptions, type?: ReceiveType<T>): Promise<IsTypeFn> {
+    const rt = runType(type);
+    return rt.createJitFunction(JitFunctions.isType, opts);
+}
+
+/** Returns a function that get Type error data. */
+export async function createTypeErrorsFn<T>(opts?: RunTypeOptions, type?: ReceiveType<T>): Promise<TypeErrorsFn> {
+    const rt = runType(type);
+    return rt.createJitFunction(JitFunctions.typeErrors, opts);
+}
+
+/**
+ * Returns a function that prepares a javascript type to be compatible with json.stringify.
+ * Allows json.stringify special types like dates, bigints, maps, set, etc... that are not supported by json.stringify
+ */
+export async function createPrepareForJsonFn<T>(opts?: RunTypeOptions, type?: ReceiveType<T>): Promise<PrepareForJsonFn> {
+    const rt = runType(type);
+    return rt.createJitFunction(JitFunctions.prepareForJson, opts);
+}
+
+/**
+ * Returns a function that restores a javascript type from json.parse.
+ * Allows restoring special types like dates, bigints, maps, set, etc... that are not supported by json.parse
+ * */
+export async function createRestoreFromJsonFn<T>(opts?: RunTypeOptions, type?: ReceiveType<T>): Promise<RestoreFromJsonFn> {
+    const rt = runType(type);
+    return rt.createJitFunction(JitFunctions.restoreFromJson, opts);
+}
+
+/**
+ * Returns a function that stringifies a javascript value to a json string.
+ * Stringifies special types like dates, bigints, maps, set, etc...
+ * Is equivalent to calling prepareForJson and then json.stringify but more efficient.
+ */
+export async function createStringifyJsonFn<T>(opts?: RunTypeOptions, type?: ReceiveType<T>): Promise<JsonStringifyFn> {
+    const rt = runType(type);
+    return rt.createJitFunction(JitFunctions.stringifyJson, opts);
+}
+
+/** Returns a function that serializes any type value to a binary format. */
+export async function createToBinaryFn<T>(opts?: RunTypeOptions, type?: ReceiveType<T>): Promise<ToBinaryFn> {
+    const rt = runType(type);
+    return rt.createJitFunction(JitFunctions.toBinary, opts);
+}
+
+/** Returns a function that deserializes a binary value to the specified type. */
+export async function createFromBinaryFn<T>(opts?: RunTypeOptions, type?: ReceiveType<T>): Promise<FromBinaryFn> {
+    const rt = runType(type);
+    return rt.createJitFunction(JitFunctions.fromBinary, opts);
+}
+
+/** Returns a function that converts a value to javascript code, including set etc */
+export function createToJavascriptFn<T>(opts?: RunTypeOptions, type?: ReceiveType<T>): ToCodeFn {
+    const rt = runType(type);
+    return rt.createJitFunction(JitFunctions.toJSCode, opts);
+}
+
+/** Returns a function that mocks a value of the specified type. */
+export async function createMockTypeFn<T>(type?: ReceiveType<T>): Promise<(opts?: Partial<RunTypeOptions>) => T> {
+    const rt = runType(type) as BaseRunType;
+    await registerJitFunctionCompiler(JitFunctions.mock);
+    return (opts?: Partial<RunTypeOptions>) => rt.mockType(opts) as T;
+}

package/src/formats.runtype.ts

@@ -0,0 +1,35 @@
+/* ########
+ * 2025 mion
+ * Author: Ma-jerez
+ * License: MIT
+ * The software is provided "as is", without warranty of any kind.
+ * ######## */
+// ###################### Types FORMATS #####################
+
+import {TypeAnnotation} from '@deepkit/core';
+// ⚠️ CRITICAL: Do NOT use `import type` - Deepkit needs the actual import for reflection!
+import {TypeFormatParams, Brand, TypeFormatPrimitives} from '@mionjs/core';
+
+/**
+ * A base type that satisfies some extra constrains. (at the moment only Branded types of strings and numbers are supported)
+ * ie: an Alphanumeric type is an string that only allow letters and numbers.
+ * ie: in Integer type is a number that only allow integer values.
+ *
+ * TypeFormat is the equivalent ot TypeAnnotation in DK but with slight modifications @deepkit/type<TypeAnnotation>
+ *
+ * @param BaseType - The base type (string, number, or bigint)
+ * @param Name - The format name used for runtime validation
+ * @param P - Format parameters for validation rules
+ * @param BrandName - Optional brand name for nominal typing (defaults to never = no brand)
+ *
+ * When BrandName is provided, the type becomes nominally branded, preventing
+ * accidental assignment of plain strings/numbers to branded types.
+ * */
+export type TypeFormat<
+    BaseType extends TypeFormatPrimitives,
+    Name extends string,
+    P extends TypeFormatParams,
+    BrandName extends string = never,
+> = [BrandName] extends [never]
+    ? BaseType & TypeAnnotation<Name, P>
+    : Brand<BaseType, BrandName> & TypeAnnotation<Name, P & {brand: BrandName}>;

package/src/jitCompilers/binary/binarySPEC.md

@@ -0,0 +1,138 @@
+# Binary Serialization/Deserialization Specification
+
+## Overview
+
+This document specifies the implementation of JIT Binary serialization and deserialization for the Mion run-types package.
+All binary serialization and deserialization functions are based on the [seqproto](https://github.com/oramasearch/seqproto) library that is highly optimized for js engines and multi-platform.
+
+This spec is designed to work and support all TypeScript features, like Unions, Intersections, etc. while leveraging seqproto's high-performance encoding strategies.
+
+All data is encoded/decoded into a single [Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) using **32-bit aligned** memory access patterns for optimal CPU performance.
+
+## SeqProto Alignment Strategy
+
+Following seqproto's approach, all data is **32-bit aligned** (4-byte boundaries) for optimal performance:
+
+- **Index tracking**: All positions tracked in 32-bit units
+- **Memory access**: Direct typed array access (`uint32Array[index]`, `float32Array[index]`)
+- **String encoding**: Uses `TextEncoder.encodeInto()` for zero-allocation encoding
+- **Buffer management**: Pre-allocated reusable buffers with simple index reset
+
+All functions used for encoding/decoding follow seqproto's optimized patterns and can be used in any JavaScript environment.
+
+## Headers and Type Markers
+
+Some variable length types and object properties require additional information. For these cases, we use **32-bit type markers** to indicate the length or type of the data that follows.
+
+### SeqProto Type Headers (32-bit aligned)
+
+SeqProto uses type markers for number encoding. All headers are 32-bit values:
+
+| Header        | Value | Description             |
+| ------------- | ----- | ----------------------- |
+| `TYPE_FLOAT`  | 0     | 32-bit IEEE 754 float   |
+| `TYPE_UINT32` | 1     | 32-bit unsigned integer |
+| `TYPE_INT32`  | 2     | 32-bit signed integer   |
+
+### Object Property Headers (Mion-specific)
+
+SeqProto doesn't handle object properties, so we define our own property encoding system:
+
+| Header Type          | Bit Layout                    | Description                                                                                          | Max Values       |
+| -------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------- |
+| **Known Property**   | no header required            | Index of the property in the Type definition, optional props that are not defined are not serialized | 65536 properties |
+| **Unknown Property** | `[length + string prop name]` | Dynamic property name                                                                                | Unlimited        |
+
+### Arrays
+
+| Collection | Bit Layout            | Description                          |
+| ---------- | --------------------- | ------------------------------------ |
+| **Array**  | `[length + elements]` | Length as uint32, number of elements |
+
+### Number Types (Type-Aware Encoding)
+
+Following seqproto's number encoding strategy:
+
+| Type                   | Bytes | Bit Layout              | Notes                           |
+| ---------------------- | ----- | ----------------------- | ------------------------------- |
+| **Integer (positive)** | 4     | `TYPE_UINT32` + `value` | `value >= 0 && value % 1 === 0` |
+| **Integer (negative)** | 4     | `TYPE_INT32` + `value`  | `value < 0 && value % 1 === 0`  |
+| **Float**              | 4     | `TYPE_FLOAT` + `value`  | `value % 1 !== 0`               |
+| **BigInt**             | 8     | `TYPE_BIGINT` + `value` |                                 |
+
+### Primitive Types (32-bit Aligned)
+
+| Type          | Bytes | Notes                                                             |
+| ------------- | ----- | ----------------------------------------------------------------- |
+| **Boolean**   | 4     | 32-bit aligned for performance                                    |
+| **Null**      | 4     | null is serialized as 0                                           |
+| **Undefined** | 4     | undefined is serialized as -1, undefined props are not serialized |
+| **Date**      | 8     | serialized as number                                              |
+
+### String Types (Zero-Allocation Encoding)
+
+| Type       | Bit Layout          | Notes                 |
+| ---------- | ------------------- | --------------------- |
+| **String** | `[length, content]` | byte length is 32 bit |
+| **RegExp** | `[source, flags]`   |                       |
+
+## Complex Types (SeqProto-Compatible)
+
+### Collection Types
+
+| Type       | Encoding Strategy                                                                          | Notes                            |
+| ---------- | ------------------------------------------------------------------------------------------ | -------------------------------- |
+| **Array**  | `uint32Array[index++] = TYPE_ARRAY; uint32Array[index++] = length; [encode each element]`  | Length + elements                |
+| **Object** | `uint32Array[index++] = TYPE_OBJECT; uint32Array[index++] = propCount; [encode each prop]` | Property count + key-value pairs |
+| **Map**    | Serialize as Array of `[key, value]` tuples                                                | Use seqproto function            |
+| **Set**    | Serialize as Array of values                                                               | Use seqproto function            |
+| **Class**  | Serialize as data only, functions are not serialized.                                      | Use object function              |
+
+### Object Serialization
+
+Object are serialized with all required props in order, this guarantee fast and simple sequential serialization/deserialization.
+Optional props are serialized as [`optional props bitmap + optional props values`].
+The bitmap for optional props is variable length but determined at compile time depending on the number of optional props min length is 4 bytes, and then the optional props.
+Each bit in the bitmap represents whether the corresponding optional prop is present or not. so the number of optional props corresponds to the number of bits to 1 in the bitmap.
+
+### Object Properties (32-bit Aligned)
+
+| Property Type          | Bit Layout                                        | Encoding                                    | Notes                                              |
+| ---------------------- | ------------------------------------------------- | ------------------------------------------- | -------------------------------------------------- |
+| **Non Optional props** | `value`                                           | `[encode value]`                            | Serialized in order they are declared in the type. |
+| **Optional props**     | `[optional props bitmap + optional props values]` |                                             |                                                    |
+| **Unknown Props**      | `[string prop name + value]`                      | `serializeString(propName); [encode value]` | used inIndexSignature or Records                   |
+
+### TypeScript Features
+
+| Feature           | Encoding Strategy                                                                              | Notes              |
+| ----------------- | ---------------------------------------------------------------------------------------------- | ------------------ |
+| **Union Types**   | `uint32Array[index++] = TYPE_UNION; uint32Array[index++] = discriminatorIndex; [encode value]` | Type index + value |
+| **Tuple**         | Serialize as Array                                                                             | Fixed-length array |
+| **Enum**          | `[type, value]` where type indicates string or number                                          |                    |
+| **Literal Types** | Serialize underlying value                                                                     |                    |
+
+#### TypeScript Features
+
+**Maps and Sets**:
+
+```typescript
+// Map<K,V> → Array<[K,V]>  → Binary Array of tuples [K,V]
+// Set<T> → Array<T> → Binary Array
+```
+
+**Union Types**:
+
+```typescript
+// Discriminated unions use type field for variant identification
+// Primitive unions encode based on runtime type detection
+// [discriminator, value]
+```
+
+**Complex Collections**:
+
+```typescript
+// Tuples → Arrays with fixed length validation
+// Records → Objects with dynamic key validation
+// Classes → Objects with constructor information
+```

package/src/jitCompilers/binary/binarySpec/binaryHelpers.ts

@@ -0,0 +1,118 @@
+/* ########
+ * 2025 mion
+ * Author: Ma-jerez
+ * License: MIT
+ * The software is provided "as is", without warranty of any kind.
+ * ######## */
+
+import {JitFunctions} from '../../../constants.functions.ts';
+import {FunctionRunType} from '../../../nodes/function/function.ts';
+import type {DataViewDeserializer, DataViewSerializer, StrictArrayBuffer} from '@mionjs/core';
+import type {InterfaceRunType} from '../../../nodes/collection/interface.ts';
+import type {RunType} from '../../../types.ts';
+import {createDataViewDeserializer, createDataViewSerializer, setSerializationOptions, getENV} from '@mionjs/core';
+import {afterAll, expect} from 'vitest';
+
+const DEBUG = getENV('DEBUG_JIT') === 'print';
+/** maps a binary serializer to json serializer */
+const toJsonSerializers: Map<(v: any) => any, (v: any) => string> = new Map();
+
+setSerializationOptions({bufferSize: 1024});
+export const serContext: DataViewSerializer = createDataViewSerializer('test');
+export const desContext: DataViewDeserializer = createDataViewDeserializer('test', new ArrayBuffer(0));
+
+const SERIALIZE_FN = JitFunctions.toBinary;
+const DESERIALIZE_FN = JitFunctions.fromBinary;
+
+export function createSerializationFns(rt: RunType) {
+    const toBinary = rt.createJitFunction(SERIALIZE_FN);
+    const fromBinary = rt.createJitFunction(DESERIALIZE_FN);
+    const serialize = (v: any) => (toBinary(v, serContext), serContext.getBuffer());
+    const deserialize = (data: StrictArrayBuffer) => (desContext.setBuffer(data), fromBinary(undefined, desContext));
+    if (DEBUG) {
+        const toJson = rt.createJitFunction(JitFunctions.prepareForJson);
+        const stringify = (v: any) => JSON.stringify(toJson(v));
+        toJsonSerializers.set(serialize, stringify);
+    }
+    return {serialize, deserialize};
+}
+
+export function createSerializationParamsFn(rt: FunctionRunType, sliceStart?: number) {
+    const params = typeof sliceStart === 'number' ? {paramsSlice: {start: sliceStart}} : undefined;
+    const toBinary = rt.createJitParamsFunction(SERIALIZE_FN, params);
+    const fromBinary = rt.createJitParamsFunction(DESERIALIZE_FN, params);
+    const serialize = (v: any) => (toBinary(v, serContext), serContext.getBuffer());
+    const deserialize = (data: StrictArrayBuffer) => (desContext.setBuffer(data), fromBinary(undefined, desContext));
+    if (DEBUG) {
+        const toJson = rt.createJitParamsFunction(JitFunctions.prepareForJson, params);
+        const stringify = (v: any) => JSON.stringify(toJson(v));
+        toJsonSerializers.set(serialize, stringify);
+    }
+    return {serialize, deserialize};
+}
+
+export function createSerializationReturnFn(rt: FunctionRunType) {
+    const toBinary = rt.createJitReturnFunction(SERIALIZE_FN);
+    const fromBinary = rt.createJitReturnFunction(DESERIALIZE_FN);
+    const serialize = (v: any) => (toBinary(v, serContext), serContext.getBuffer());
+    const deserialize = (data: StrictArrayBuffer) => (desContext.setBuffer(data), fromBinary(undefined, desContext));
+    if (DEBUG) {
+        const toJson = rt.createJitReturnFunction(JitFunctions.prepareForJson);
+        const stringify = (v: any) => JSON.stringify(toJson(v));
+        toJsonSerializers.set(serialize, stringify);
+    }
+    return {serialize, deserialize};
+}
+
+export function createSerializationCallSignatureParamsFn(rt: InterfaceRunType) {
+    const callSignature = rt.getCallSignature()!;
+    const toBinary = callSignature.createJitParamsFunction(SERIALIZE_FN);
+    const fromBinary = callSignature.createJitParamsFunction(DESERIALIZE_FN);
+    const serialize = (v: any) => (toBinary(v, serContext), serContext.getBuffer());
+    const deserialize = (data: StrictArrayBuffer) => (desContext.setBuffer(data), fromBinary(undefined, desContext));
+    if (DEBUG) {
+        const toJson = callSignature.createJitParamsFunction(JitFunctions.prepareForJson);
+        const stringify = (v: any) => JSON.stringify(toJson(v));
+        toJsonSerializers.set(serialize, stringify);
+    }
+    return {serialize, deserialize};
+}
+
+export function createSerializationCallSignatureReturnFn(rt: InterfaceRunType) {
+    const callSignature = rt.getCallSignature()!;
+    const toBinary = callSignature.createJitReturnFunction(SERIALIZE_FN);
+    const fromBinary = callSignature.createJitReturnFunction(DESERIALIZE_FN);
+    const serialize = (v: any) => (toBinary(v, serContext), serContext.getBuffer());
+    const deserialize = (data: StrictArrayBuffer) => (desContext.setBuffer(data), fromBinary(undefined, desContext));
+    if (DEBUG) {
+        const toJson = callSignature.createJitReturnFunction(JitFunctions.prepareForJson);
+        const stringify = (v: any) => JSON.stringify(toJson(v));
+        toJsonSerializers.set(serialize, stringify);
+    }
+    return {serialize, deserialize};
+}
+
+const sizesEntries: any[] = [];
+const valuesEntries: any[] = [];
+
+export function roundTrip(serialize: (v: any) => StrictArrayBuffer, deserialize: (v: StrictArrayBuffer) => any, value: any) {
+    serContext.reset();
+    const serialized = serialize(value);
+    const deserialized = deserialize(serialized);
+    if (DEBUG) {
+        const stringify = toJsonSerializers.get(serialize)!;
+        let json: number | string = '';
+        // eslint-disable-next-line
+        try { json = new Blob([stringify(value)]).size; } catch (e) { json = '-'; } // prettier-ignore
+        const sizes = {name: expect.getState().currentTestName, json, binary: serialized.byteLength};
+        sizesEntries.push(sizes);
+        valuesEntries.push({value, deserialized});
+    }
+    const result = {serialized, deserialized};
+    return result;
+}
+
+afterAll(() => {
+    if (sizesEntries.length) console.table(sizesEntries);
+    if (valuesEntries.length) console.table(valuesEntries);
+});