@mionjs/run-types 0.8.6 → 0.8.8

package/index.ts

@@ -0,0 +1,70 @@
+/* ########
+ * 2024 mion
+ * Author: Ma-jerez
+ * License: MIT
+ * The software is provided "as is", without warranty of any kind.
+ * ######## */
+
+// Re-export all modules from the package.json exports field
+export * from './src/types.ts';
+export * from './src/constants.functions.ts';
+export * from './src/constants.kind.ts';
+export * from './src/constants.ts';
+export * from './src/createRunType.ts';
+export * from './src/createRunTypeFunctions.ts';
+export * from './src/formats.runtype.ts';
+export * from './src/lib/typeId.ts';
+export * from './src/lib/dkProxy.ts';
+export * from './src/lib/baseRunTypeFormat.ts';
+export * from './src/lib/baseRunTypes.ts';
+export * from './src/lib/formats.ts';
+export * from './src/lib/guards.ts';
+export * from './src/lib/jitFnCompiler.ts';
+export * from './src/lib/jitFnsRegistry.ts';
+export * from './src/mocking/constants.mock.ts';
+export * from './src/mocking/mockRegistry.ts';
+export * from './src/mocking/mockType.ts';
+export * from './src/mocking/mockUtils.ts';
+export * from './src/run-types-pure-fns.ts';
+
+// TODO: decide if we want to export all nodes or not
+export type * from './src/nodes/atomic/any.ts';
+export type * from './src/nodes/atomic/bigInt.ts';
+export type * from './src/nodes/atomic/boolean.ts';
+export type * from './src/nodes/atomic/date.ts';
+export type * from './src/nodes/atomic/enum.ts';
+export type * from './src/nodes/atomic/enumMember.ts';
+export type * from './src/nodes/atomic/literal.ts';
+export type * from './src/nodes/atomic/never.ts';
+export type * from './src/nodes/atomic/null.ts';
+export type * from './src/nodes/atomic/number.ts';
+export type * from './src/nodes/atomic/object.ts';
+export type * from './src/nodes/atomic/regexp.ts';
+export type * from './src/nodes/atomic/string.ts';
+export type * from './src/nodes/atomic/symbol.ts';
+export type * from './src/nodes/atomic/undefined.ts';
+export type * from './src/nodes/atomic/unknown.ts';
+export type * from './src/nodes/atomic/void.ts';
+export type * from './src/nodes/collection/class.ts';
+export type * from './src/nodes/collection/functionParams.ts';
+export type * from './src/nodes/collection/interface.ts';
+export type * from './src/nodes/collection/intersection.ts';
+export type * from './src/nodes/collection/tuple.ts';
+export type * from './src/nodes/collection/union.ts';
+export type * from './src/nodes/collection/unionDiscriminator.ts';
+export type * from './src/nodes/function/function.ts';
+export type * from './src/nodes/member/array.ts';
+export type * from './src/nodes/member/callSignature.ts';
+export type * from './src/nodes/member/genericMember.ts';
+export type * from './src/nodes/member/indexProperty.ts';
+export type * from './src/nodes/member/method.ts';
+export type * from './src/nodes/member/methodSignature.ts';
+export type * from './src/nodes/member/param.ts';
+export type * from './src/nodes/member/property.ts';
+export type * from './src/nodes/member/restParams.ts';
+export type * from './src/nodes/member/tupleMember.ts';
+export type * from './src/nodes/native/Iterable.ts';
+export type * from './src/nodes/native/map.ts';
+export type * from './src/nodes/native/nonSerializable.ts';
+export type * from './src/nodes/native/promise.ts';
+export type * from './src/nodes/native/set.ts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mionjs/run-types",
-  "version": "0.8.6",
+  "version": "0.8.8",
   "type": "module",
   "description": "Run time functionality directly from typescript types",
   "keywords": [
@@ -35,7 +35,11 @@
     "lib": ".dist"
   },
   "files": [
-    ".dist"
+    ".dist",
+    "index.ts",
+    "src",
+    "!src/**/*.spec.ts",
+    "!src/**/*.test.ts"
   ],
   "repository": {
     "type": "git",
@@ -60,7 +64,10 @@
   "dependencies": {
     "@deepkit/core": "1.0.19",
     "@deepkit/type": "1.0.19",
-    "@mionjs/core": "0.8.6"
+    "@mionjs/core": "0.8.8"
   },
-  "gitHead": "612302e243365c01fadbf3351b857174bf2f3956"
+  "peerDependencies": {
+    "typescript": ">=6.0.0"
+  },
+  "gitHead": "a92a438011336a078d394b75054422f3a56f8468"
 }

package/src/constants.functions.ts

@@ -0,0 +1,196 @@
+/* ########
+ * 2025 mion
+ * Author: Ma-jerez
+ * License: MIT
+ * The software is provided "as is", without warranty of any kind.
+ * ######## */
+
+import {type JitFnArgs, JIT_FUNCTION_IDS} from '@mionjs/core';
+
+/** Javascript code types */
+export const CodeTypes = {
+    expression: 'E', // single expression, that could be concatenated using js operators like + - * && || etc...
+    statement: 'S', // one or multiple statements, that could be concatenated using ; to ensure correct syntax
+    returnBlock: 'RB', // code block, it can not be concatenated with other code, it has an explicit return statement and needs to be wrapped in a function
+} as const;
+export type CodeType = (typeof CodeTypes)[keyof typeof CodeTypes];
+
+export interface JitFnSettings {
+    id: string;
+    name: string;
+    /** dynamically imports a single compiler function that is capable of compiling any node
+     * @see {@link ./jitCompilers/stringifyJson.ts#visitJsonStringify} as example of compiler function
+     */
+    import?: () => Promise<(...args: any[]) => any>;
+    jitArgs: JitFnArgs;
+    jitDefaultArgs: JitFnArgs;
+    returnName: string;
+    /**
+     * When no initial vλl is required by the function.
+     * This is typically used by deserializers, that do not transform the input value but create a new one from other params.
+     * an the initial vλl is used as a variable initialization for the returned values.
+     * ie binary deserialization
+     */
+    noInitialVλl?: true;
+    runTimeOptions?: Record<string, {keyName: string; type: 'boolean' | 'number' | 'string'; defaultValue: any}>;
+    /**
+     * When set to true, the format code should replace the jit code for the function.
+     * This is used when the format code is more efficient than the default code.
+     */
+    formatShouldReplaceJitCode?: true;
+} // list of available jit functions
+
+// variable names used in jit functions
+// JitUtils is passed with the name 'utl'. it is hardcoded in all jit code to avoid string interpolation
+export const jitArgs = {vλl: 'v'} as const;
+export const jitDefaultArgs = {vλl: ''} as const;
+export const jitErrorArgs = {vλl: 'v', pλth: 'pth', εrr: 'er'} as const;
+export const jitDefaultErrorArgs = {vλl: '', pλth: '[]', εrr: '[]'} as const;
+export const jitArgsWithOptions = {vλl: 'v', θpts: 'opts'} as const;
+export const jitDefaultArgsWithOptions = {vλl: '', θpts: '{}'} as const;
+export const jitBinarySerializerArgs = {vλl: 'v', sεr: 'Ser'} as const; // vλl = js value to serialize ser = serializer,
+export const jitBinaryDeserializerArgs = {vλl: 'ret', dεs: 'Des'} as const; // vλl is used as return variable ans is assigned the deserialized value, des = deserializer
+export const jitDefaultBinarySerializerArgs = {vλl: '', sεr: ''} as const;
+export const jitDefaultBinaryDeserializerArgs = {vλl: '', dεs: ''} as const;
+
+// ######## !IMPORTANT: ALL JIT FUNCTIONS IDs MUST BE UNIQUE and short ########
+
+type JitFunctionsGroup = {[key: string]: JitFnSettings};
+
+export const jitValidationFunctions = {
+    isType: {
+        id: JIT_FUNCTION_IDS.isType,
+        name: 'isType',
+        jitArgs,
+        jitDefaultArgs,
+        returnName: jitArgs.vλl,
+    },
+    typeErrors: {
+        id: JIT_FUNCTION_IDS.typeErrors,
+        name: 'typeErrors',
+        jitArgs: jitErrorArgs,
+        jitDefaultArgs: jitDefaultErrorArgs,
+        returnName: jitErrorArgs.εrr,
+    },
+} as const satisfies JitFunctionsGroup;
+
+export const jitSerializationFunctions = {
+    prepareForJson: {
+        id: JIT_FUNCTION_IDS.prepareForJson,
+        name: 'prepareForJson',
+        jitArgs,
+        jitDefaultArgs,
+        returnName: jitArgs.vλl,
+    },
+    restoreFromJson: {
+        id: JIT_FUNCTION_IDS.restoreFromJson,
+        name: 'restoreFromJson',
+        jitArgs,
+        jitDefaultArgs,
+        returnName: jitArgs.vλl,
+    },
+    stringifyJson: {
+        id: JIT_FUNCTION_IDS.stringifyJson,
+        name: 'stringifyJson',
+        jitArgs,
+        jitDefaultArgs,
+        returnName: jitArgs.vλl,
+    },
+    // similar to json stringify but outputs js code, including pure functions, already imported as size is quite small
+    toJSCode: {
+        id: JIT_FUNCTION_IDS.toJSCode,
+        name: 'toJSCode',
+        jitArgs,
+        jitDefaultArgs,
+        returnName: jitArgs.vλl,
+    },
+    // Binary serialization functions
+    toBinary: {
+        id: JIT_FUNCTION_IDS.toBinary,
+        name: 'toBinary',
+        jitArgs: jitBinarySerializerArgs,
+        jitDefaultArgs: jitDefaultBinarySerializerArgs,
+        // returns the serializer buffer
+        returnName: jitBinarySerializerArgs.sεr,
+        formatShouldReplaceJitCode: true,
+    },
+    fromBinary: {
+        id: JIT_FUNCTION_IDS.fromBinary,
+        name: 'fromBinary',
+        jitArgs: jitBinaryDeserializerArgs,
+        jitDefaultArgs: jitDefaultBinaryDeserializerArgs,
+        // deserialized value is stored in vλl that is initially undefined
+        returnName: jitBinaryDeserializerArgs.vλl,
+        noInitialVλl: true,
+        formatShouldReplaceJitCode: true,
+    },
+    // apply type formatters, ie: lowercase, uppercase, trim, etc
+    format: {
+        id: JIT_FUNCTION_IDS.format,
+        name: 'format',
+        jitArgs,
+        jitDefaultArgs,
+        returnName: jitArgs.vλl,
+    },
+} as const satisfies JitFunctionsGroup;
+
+export const JitFunctions = {
+    ...jitValidationFunctions,
+    ...jitSerializationFunctions,
+    unknownKeyErrors: {
+        id: JIT_FUNCTION_IDS.unknownKeyErrors,
+        name: 'unknownKeyErrors',
+        jitArgs: jitErrorArgs,
+        jitDefaultArgs: jitDefaultErrorArgs,
+        returnName: jitErrorArgs.εrr,
+    },
+    hasUnknownKeys: {
+        id: JIT_FUNCTION_IDS.hasUnknownKeys,
+        name: 'hasUnknownKeys',
+        jitArgs: jitArgsWithOptions,
+        jitDefaultArgs: jitDefaultArgsWithOptions,
+        runTimeOptions: {checkNonJitProps: {keyName: 'checkNonJitProps', type: 'boolean', defaultValue: false}},
+        returnName: jitArgsWithOptions.vλl,
+    },
+    stripUnknownKeys: {
+        id: JIT_FUNCTION_IDS.stripUnknownKeys,
+        name: 'stripUnknownKeys',
+        jitArgs,
+        jitDefaultArgs,
+        returnName: jitArgs.vλl,
+    },
+    unknownKeysToUndefined: {
+        id: JIT_FUNCTION_IDS.unknownKeysToUndefined,
+        name: 'unknownKeysToUndefined',
+        jitArgs,
+        jitDefaultArgs,
+        returnName: jitArgs.vλl,
+    },
+    aux: {
+        id: JIT_FUNCTION_IDS.aux,
+        name: 'aux',
+        jitArgs,
+        jitDefaultArgs,
+        returnName: jitArgs.vλl,
+    },
+    // mock is not really a jit function but is used in a similar way, main difference is that it is not compiled
+    mock: {
+        id: JIT_FUNCTION_IDS.mock,
+        name: 'mockType',
+        import: () => import('./mocking/mockType.ts').then((m) => m.mockType),
+        jitArgs,
+        jitDefaultArgs,
+        returnName: jitArgs.vλl,
+    },
+    // pure function are not jit compiled but we ensure we reserve a prefix to avoid collisions
+    pureFunction: {
+        id: JIT_FUNCTION_IDS.pureFunction,
+        name: 'pureFunction',
+        jitArgs,
+        jitDefaultArgs,
+        returnName: jitArgs.vλl,
+    },
+} as const satisfies JitFunctionsGroup;
+
+export const jitFunctionList: JitFnSettings[] = Object.values(JitFunctions);
+export const jitFunctionsById = Object.fromEntries(jitFunctionList.map((f) => [f.id, f]));

package/src/constants.kind.ts

@@ -0,0 +1,76 @@
+/* ########
+ * 2024 mion
+ * Author: Ma-jerez
+ * License: MIT
+ * The software is provided "as is", without warranty of any kind.
+ * ######## */
+
+import {ReflectionKind} from '@deepkit/type';
+import {RunType} from './types.ts';
+
+export const ReflectionKindName: {[key: number]: keyof typeof ReflectionKind} = {
+    0: 'never',
+    1: 'any',
+    2: 'unknown',
+    3: 'void',
+    4: 'objectLiteral', // name was changed from deepkit's 'object' to 'objectLiteral'
+    5: 'string',
+    6: 'number',
+    7: 'boolean',
+    8: 'symbol',
+    9: 'bigint',
+    10: 'null',
+    11: 'undefined',
+    12: 'regexp',
+    13: 'literal',
+    14: 'templateLiteral',
+    15: 'property',
+    16: 'method',
+    17: 'function',
+    18: 'parameter',
+    19: 'promise',
+    20: 'class',
+    21: 'typeParameter',
+    22: 'enum',
+    23: 'union',
+    24: 'intersection',
+    25: 'array',
+    26: 'tuple',
+    27: 'tupleMember',
+    28: 'enumMember',
+    29: 'rest',
+    30: 'object', // name was changed from deepkit's 'objectLiteral' to 'object' for better error messages
+    31: 'indexSignature',
+    32: 'propertySignature',
+    33: 'methodSignature',
+    34: 'infer',
+    35: 'callSignature',
+};
+
+// ReflectionKind from deepkit is extended with the following sub kinds
+export const ReflectionSubKind = {
+    // group of sub-kinds that extends ReflectionKind.class
+    date: 20_01,
+    map: 20_02,
+    set: 20_03,
+    nonSerializable: 20_04,
+
+    params: 17_01,
+    mapKey: 18_01,
+    mapValue: 18_02,
+    setItem: 18_03,
+} as const;
+
+export const ReflectionSubNames: {[key: number]: keyof typeof ReflectionSubKind} = {
+    20_01: 'date',
+    20_02: 'map',
+    20_03: 'set',
+    17_01: 'params',
+} as const;
+
+export type AnyKindName = keyof typeof ReflectionKind | keyof typeof ReflectionSubKind;
+
+export function getReflectionName(rt: RunType): AnyKindName {
+    if (rt.src.subKind) return ReflectionSubNames[rt.src.subKind];
+    return ReflectionKindName[rt.src.kind];
+}

package/src/constants.ts

@@ -0,0 +1,85 @@
+/* ########
+ * 2024 mion
+ * Author: Ma-jerez
+ * License: MIT
+ * The software is provided "as is", without warranty of any kind.
+ * ######## */
+
+// native javascript objects that are not serializable
+export const nonSerializableClasses = [
+    // TODO: decide what to do with native errors, they should be easily serializable
+    Error,
+    EvalError,
+    RangeError,
+    ReferenceError,
+    SyntaxError,
+    TypeError,
+    URIError,
+    AggregateError,
+    // Promise, // Promise has it's own RunType
+    // data types
+    WeakMap,
+    WeakSet,
+    DataView,
+    ArrayBuffer,
+    SharedArrayBuffer,
+    Float32Array,
+    Float64Array,
+    Int8Array,
+    Int16Array,
+    Int32Array,
+    Uint8Array,
+    Uint8ClampedArray,
+    Uint16Array,
+    Uint32Array,
+    BigInt64Array,
+    BigUint64Array,
+];
+
+// these are global objects that are not serializable.
+// values are repeated from nonSerializableClasses, as if they are classes or global object depends in typescript stn lib types and these can change
+export const nonSerializableGlobals = [
+    // TODO: decide what to do with native errors, they should be easily serializable
+    'Error',
+    'EvalError',
+    'RangeError',
+    'ReferenceError',
+    'SyntaxError',
+    'TypeError',
+    'URIError',
+    'AggregateError',
+    // data types
+    'WeakMap',
+    'WeakSet',
+    'DataView',
+    'ArrayBuffer',
+    'SharedArrayBuffer',
+    'Float32Array',
+    'Float64Array',
+    'Int8Array',
+    'Int16Array',
+    'Int32Array',
+    'Uint8Array',
+    'Uint8ClampedArray',
+    'Uint16Array',
+    'Uint32Array',
+    'BigInt64Array',
+    'BigUint64Array',
+    // bellow are common interface names from standard libraries, they added here but not tested
+    'Generator',
+    'GeneratorFunction',
+    'AsyncGenerator',
+    'Iterator',
+    'AsyncGeneratorFunction',
+    'AsyncIterator',
+];
+
+// typescript utility types
+export const nativeUtilityStringTypes = ['Uppercase', 'Lowercase', 'Capitalize', 'Uncapitalize'];
+
+// other constants
+export const validPropertyNameRegExp = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+export const maxStackErrorMessage =
+    'Max compilation nested level reached, either you have a very deeply nested type or there is an error related to circular references un the types.';
+export const JIT_STACK_TRACE_MESSAGE = '\nJIT runType trace => ';
+export const MAX_UNION_ITEMS = 2 ** 16 - 1;