@mionjs/run-types 0.8.6 → 0.8.8

package/src/createRunType.ts

@@ -0,0 +1,323 @@
+/* eslint-disable no-case-declarations */
+/* ########
+ * 2024 mion
+ * Author: Ma-jerez
+ * License: MIT
+ * The software is provided "as is", without warranty of any kind.
+ * ######## */
+
+import type {RunType, Mutable, SrcType} from './types.ts';
+import type {BaseRunType} from './lib/baseRunTypes.ts';
+import type {TypeClass, Type} from '@deepkit/type';
+import {ReflectionKind, resolveReceiveType, ReceiveType, reflect, typeAnnotation, stringifyType} from '@deepkit/type';
+import {
+    hasArguments,
+    hasExtendsArguments,
+    hasImplements,
+    hasIndexType,
+    hasParameters,
+    hasReturn,
+    hasType,
+    hasTypes,
+    isNativeUtilityStringTypes,
+    isNonSerializableClass,
+    isNonSerializableObject,
+} from './lib/guards.ts';
+import {StringRunType} from './nodes/atomic/string.ts';
+import {DateRunType} from './nodes/atomic/date.ts';
+import {NumberRunType} from './nodes/atomic/number.ts';
+import {BooleanRunType} from './nodes/atomic/boolean.ts';
+import {NullRunType} from './nodes/atomic/null.ts';
+import {BigIntRunType} from './nodes/atomic/bigInt.ts';
+import {AnyRunType} from './nodes/atomic/any.ts';
+import {UndefinedRunType} from './nodes/atomic/undefined.ts';
+import {UnknownRunType} from './nodes/atomic/unknown.ts';
+import {VoidRunType} from './nodes/atomic/void.ts';
+import {ArrayRunType} from './nodes/member/array.ts';
+import {LiteralRunType} from './nodes/atomic/literal.ts';
+import {RegexpRunType} from './nodes/atomic/regexp.ts';
+import {NeverRunType} from './nodes/atomic/never.ts';
+import {EnumRunType} from './nodes/atomic/enum.ts';
+import {EnumMemberRunType} from './nodes/atomic/enumMember.ts';
+import {UnionRunType} from './nodes/collection/union.ts';
+import {TupleRunType} from './nodes/collection/tuple.ts';
+import {FunctionParamsRunType} from './nodes/collection/functionParams.ts';
+import {TupleMemberRunType} from './nodes/member/tupleMember.ts';
+import {InterfaceRunType} from './nodes/collection/interface.ts';
+import {PropertyRunType} from './nodes/member/property.ts';
+import {IndexSignatureRunType} from './nodes/member/indexProperty.ts';
+import {MethodSignatureRunType} from './nodes/member/methodSignature.ts';
+import {CallSignatureRunType} from './nodes/member/callSignature.ts';
+import {FunctionRunType} from './nodes/function/function.ts';
+import {PromiseRunType} from './nodes/native/promise.ts';
+import {ObjectRunType} from './nodes/atomic/object.ts';
+import {IntersectionRunType} from './nodes/collection/intersection.ts';
+import {ParameterRunType} from './nodes/member/param.ts';
+import {MethodRunType} from './nodes/member/method.ts';
+import {RestParamsRunType} from './nodes/member/restParams.ts';
+import {ClassRunType} from './nodes/collection/class.ts';
+import {MapRunType} from './nodes/native/map.ts';
+import {ReflectionSubKind} from './constants.kind.ts';
+import {SetRunType} from './nodes/native/set.ts';
+import {SymbolRunType} from './nodes/atomic/symbol.ts';
+import {NonSerializableRunType} from './nodes/native/nonSerializable.ts';
+import {registerErrorDeserializers} from '@mionjs/core';
+
+export function runType<T>(type?: ReceiveType<T>): RunType {
+    const start = Date.now();
+    const src = resolveReceiveType(type) as SrcType;
+    const took0 = Date.now() - start;
+    createRunTypes(src);
+    const took1 = Date.now() - start;
+    const diff = took1 - took0;
+    // max RunType overhead 60 ms
+    if (diff > 60) console.warn(`RunType overhead is very long: ${diff}ms for ${stringifyType(src)}`);
+    return src._rt;
+}
+
+export function reflectFunction<Fn extends (...args: any[]) => any>(fn: Fn): FunctionRunType {
+    const src = reflect(fn) as SrcType;
+    runType(src);
+    return src._rt as FunctionRunType;
+}
+
+// We need to traverse all possible associated nodes to create all the runTypes
+function createRunTypes(src: SrcType): void {
+    registerErrorDeserializers();
+    const stack: Type[] = [src];
+
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current || (current as SrcType)._rt) continue;
+
+        try {
+            createRunType(current as Mutable<SrcType>);
+        } catch (error) {
+            const typesStackMessage = '\nTypes Stack: ' + stack.map((t) => t.typeName || t.kind).join(', ');
+            (error as Error).message += typesStackMessage;
+            throw error;
+        }
+
+        // single child type nodes
+        if (hasType(current)) stack.push(current.type);
+        if (hasReturn(current)) stack.push(current.return);
+        if (hasIndexType(current)) stack.push(current.indexType);
+        if (current.origin) stack.push(current.origin);
+        if (current.indexAccessOrigin?.index) stack.push(current.indexAccessOrigin?.index);
+        if (current.indexAccessOrigin?.container) stack.push(current.indexAccessOrigin?.container);
+
+        // multiple child type nodes
+        if (hasTypes(current)) pushToStack(current.types, stack);
+        if (hasParameters(current)) pushToStack(current.parameters, stack);
+        if (hasArguments(current)) pushToStack(current.arguments, stack);
+        if (hasExtendsArguments(current)) pushToStack(current.extendsArguments, stack);
+        if (hasImplements(current)) pushToStack(current.implements, stack);
+        if (current.typeArguments) pushToStack(current.typeArguments, stack);
+        if (current.decorators) pushToStack(current.decorators, stack);
+        if (current.scheduleDecorators) pushToStack(current.scheduleDecorators, stack);
+
+        // annotations
+        if (current.annotations) {
+            const annotations = typeAnnotation.getAnnotations(current);
+            for (const annotation of annotations) stack.push(annotation.options);
+        }
+
+        // originTypes
+        current.originTypes?.forEach((ot) => {
+            if (ot.typeArguments) pushToStack(ot.typeArguments, stack);
+        });
+
+        // sometimes parent is an orphan so we need to explicitly add it to the stack
+        if (current.parent && !(current.parent as SrcType)?._rt) stack.push(current.parent);
+    }
+}
+
+function pushToStack(subTypes: Type[], stack: Type[]) {
+    if (Array.isArray(subTypes)) stack.push(...subTypes);
+}
+
+function createRunType(deepkitType: Mutable<SrcType>): RunType {
+    // console.log('deepkitType', deepkitType);
+
+    /*
+     RunType reference is stored in the deepkitType._runType so we can access both the deepkitType and the mion RunType,
+     basically every runType stores a reference to a deepkit type and vice versa.
+     This also relies on deepkit handling circular types to prevent infinite loop when we are generating RunTypes.
+    */
+    const existingType: RunType | undefined = deepkitType._rt;
+    // TODO: IMPORTANT: seems like deepkit can generate multiple types objects for the same type, so we need to handle this
+    // we are attaching the runType to the deepkit type (deepkitType._runType), to link the two types together
+    // but as deepkit can generate multiple types that means existingType will be null and the markAsCircular function is not working as expected
+    if (existingType) return existingType;
+
+    let rt: BaseRunType;
+
+    switch (deepkitType.kind) {
+        // ###################### ATOMIC RUNTYPES ######################
+        // Primitive types and other atomic types that don't contain other types
+        case ReflectionKind.any:
+            rt = new AnyRunType();
+            break;
+        case ReflectionKind.bigint:
+            rt = new BigIntRunType();
+            break;
+        case ReflectionKind.boolean:
+            rt = new BooleanRunType();
+            break;
+        case ReflectionKind.enum:
+            rt = new EnumRunType();
+            break;
+        case ReflectionKind.enumMember:
+            // enum members are resolved by the enum type, so this is not expected to be called
+            rt = new EnumMemberRunType();
+            break;
+        case ReflectionKind.literal:
+            rt = new LiteralRunType();
+            break;
+        case ReflectionKind.never:
+            // TODO add the string format feature
+            rt = isNativeUtilityStringTypes(deepkitType) ? new StringRunType() : new NeverRunType();
+            break;
+        case ReflectionKind.null:
+            rt = new NullRunType();
+            break;
+        case ReflectionKind.number:
+            rt = new NumberRunType();
+            break;
+        case ReflectionKind.object:
+            rt = new ObjectRunType();
+            break;
+        case ReflectionKind.regexp:
+            rt = new RegexpRunType();
+            break;
+        case ReflectionKind.string:
+            rt = new StringRunType();
+            break;
+        case ReflectionKind.symbol:
+            rt = new SymbolRunType();
+            break;
+        case ReflectionKind.templateLiteral:
+            // deepkit automatically resolves template literals unions to literals
+            // this is only called when you define the type of a template literal i.e: type T = `foo${string}`;
+            // this is not supported at the moment but would be useful for type safe urls etc
+            throw new Error(
+                'Template Literals are resolved by the compiler to Literals ie: const tl = `${string}World`. Template literal types are not supported. ie type TL = `${string}World`'
+            );
+        case ReflectionKind.undefined:
+            rt = new UndefinedRunType();
+            break;
+        case ReflectionKind.unknown:
+            rt = new UnknownRunType();
+            break;
+        case ReflectionKind.void:
+            rt = new VoidRunType();
+            break;
+
+        // ###################### MEMBER RUNTYPES ######################
+        // Types that represent members of collections or other structures
+        case ReflectionKind.array:
+            rt = new ArrayRunType();
+            break;
+        case ReflectionKind.callSignature:
+            rt = new CallSignatureRunType();
+            break;
+        case ReflectionKind.function:
+            if (deepkitType.subKind === ReflectionSubKind.params) {
+                rt = new FunctionParamsRunType();
+            } else {
+                const frt = new FunctionRunType();
+                // TODO review an change how we compile function parameters and return type
+                // those should also be jit functions, no need to check for array
+                // and maybe add option to target individual parameters
+                (frt.parameterRunTypes as Mutable<RunType>).src = deepkitType;
+                rt = frt;
+            }
+            break;
+        case ReflectionKind.indexSignature:
+            rt = new IndexSignatureRunType();
+            break;
+        case ReflectionKind.method:
+            rt = new MethodRunType();
+            break;
+        case ReflectionKind.methodSignature:
+            rt = new MethodSignatureRunType();
+            break;
+        case ReflectionKind.parameter:
+            rt = new ParameterRunType();
+            break;
+        case ReflectionKind.property:
+        case ReflectionKind.propertySignature:
+            rt = new PropertyRunType();
+            break;
+        case ReflectionKind.rest:
+            rt = new RestParamsRunType();
+            break;
+        case ReflectionKind.tupleMember:
+            rt = new TupleMemberRunType();
+            break;
+        case ReflectionKind.promise:
+            rt = new PromiseRunType();
+            break;
+
+        // ###################### COLLECTION RUNTYPES ######################
+        case ReflectionKind.objectLiteral:
+            if (isNonSerializableObject(deepkitType)) {
+                rt = new NonSerializableRunType();
+            } else {
+                rt = new InterfaceRunType();
+            }
+            break;
+        case ReflectionKind.class:
+            rt = initClassRunType(deepkitType);
+            break;
+        // Types that contain other types as members
+        case ReflectionKind.infer:
+            throw new Error(
+                'Infer type not supported, ie: type MyType =Type<T> = T extends (...args: any[]) => infer R ? R : any; https://www.typescriptlang.org/docs/handbook/2/conditional-types.html'
+            );
+
+        case ReflectionKind.intersection:
+            rt = new IntersectionRunType();
+            break;
+
+        case ReflectionKind.tuple:
+            rt = new TupleRunType();
+            break;
+        case ReflectionKind.typeParameter:
+            throw new Error(
+                'TypeParameter not implemented. Type parameters are the generic placeholders in type definitions (e.g., T in Array<T>, ErrType in TypedError<ErrType>). ' +
+                    'Type parameters are typically resolved during type instantiation and should not appear in runtime type checking.' +
+                    'This error is typically caused by a generic type missing type arguments, e.g.: TypedError instead of TypedError<"my-error">.'
+            );
+        // rType = resolveTypeParameter(deepkitType, opts, mapper);
+        case ReflectionKind.union:
+            rt = new UnionRunType();
+            break;
+        default:
+            rt = new AnyRunType();
+            break;
+    }
+    rt.onCreated(deepkitType);
+    // console.log('rt', rt);
+    return rt;
+}
+
+function initClassRunType(src: TypeClass & {subKind?: number}): BaseRunType {
+    switch (src.classType) {
+        case Date:
+            src.subKind = ReflectionSubKind.date;
+            return new DateRunType();
+        case Map:
+            src.subKind = ReflectionSubKind.map;
+            return new MapRunType();
+        case Set:
+            src.subKind = ReflectionSubKind.set;
+            return new SetRunType();
+        default:
+            if (isNonSerializableClass(src)) {
+                src.subKind = ReflectionSubKind.nonSerializable;
+                return new NonSerializableRunType();
+            }
+            return new ClassRunType();
+    }
+}

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
+```