@nhtio/encoder 0.1.0-master-ab456424

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@nhtio/encoder",
+  "version": "0.1.0-master-ab456424",
+  "description": "A portable cross-environment encoder / decoder for complex and structured data",
+  "keywords": [],
+  "author": "Jak Giveon <jak@nht.io>",
+  "copyright": "© 2025-present New Horizon Technology LTD",
+  "license": "MIT",
+  "module": "./index.mjs",
+  "main": "./index.cjs",
+  "exports": {
+    ".": {
+      "import": "./index.mjs",
+      "require": "./index.cjs",
+      "types": "./index.d.ts"
+    },
+    "./exceptions": {
+      "import": "./exceptions.mjs",
+      "require": "./exceptions.cjs",
+      "types": "./exceptions.d.ts"
+    },
+    "./types": {
+      "import": "./types.mjs",
+      "require": "./types.cjs",
+      "types": "./types.d.ts"
+    }
+  },
+  "packageManager": "pnpm@10.8.0+sha512.0e82714d1b5b43c74610193cb20734897c1d00de89d0e18420aebc5977fa13d780a9cb05734624e81ebd81cc876cd464794850641c48b9544326b5622ca29971",
+  "type": "module",
+  "dependencies": {}
+}

package/private/exceptions.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Base exception class that extends the native Error class.
+ * Provides a foundation for all custom exceptions with additional metadata
+ * like error codes, status codes, and help descriptions.
+ */
+export declare class BaseException extends Error {
+    /**
+     * Define the error metadata as static properties to avoid
+     * setting them repeatedly on the error instance
+     */
+    static help?: string;
+    static code?: string;
+    static status?: number;
+    static message?: string;
+    /**
+     * Name of the class that raised the exception.
+     */
+    name: string;
+    /**
+     * Optional help description for the error. You can use it to define additional
+     * human readable information for the error.
+     */
+    help?: string;
+    /**
+     * A machine readable error code. This will allow the error handling logic
+     * to narrow down exceptions based upon the error code.
+     */
+    code?: string;
+    /**
+     * A status code for the error. Usually helpful when converting errors
+     * to HTTP responses.
+     */
+    status: number;
+    /**
+     * Creates a new BaseException instance.
+     *
+     * @param message - The error message. If not provided, uses the static message from the constructor.
+     * @param options - Additional options including error cause, code, and status.
+     */
+    constructor(message?: string, options?: ErrorOptions & {
+        code?: string;
+        status?: number;
+    });
+    /**
+     * Returns the constructor name for the Symbol.toStringTag property.
+     *
+     * @returns The name of the exception class.
+     */
+    get [Symbol.toStringTag](): string;
+    /**
+     * Returns a string representation of the exception.
+     * Includes the error code in brackets if available.
+     *
+     * @returns A formatted string representation of the exception.
+     */
+    toString(): string;
+}
+/**
+ * Exception thrown when a value cannot be encoded.
+ * This indicates that the value type is not supported by the encoder.
+ */
+export declare class E_UNENCODABLE_VALUE extends BaseException {
+    static status: number;
+    static code: string;
+    /**
+     * Creates a new E_UNENCODABLE_VALUE exception.
+     *
+     * @param value - The value that could not be encoded.
+     */
+    constructor(value: unknown);
+}
+/**
+ * Exception thrown when encoding fails due to an underlying error.
+ * This wraps the original error as the cause for better error tracing.
+ */
+export declare class E_ENCODING_FAILED extends BaseException {
+    static status: number;
+    static code: string;
+    /**
+     * Creates a new E_ENCODING_FAILED exception.
+     *
+     * @param value - The value that failed to encode.
+     * @param cause - The underlying error that caused the encoding to fail.
+     */
+    constructor(value: unknown, cause: unknown);
+}
+/**
+ * Exception thrown when a circular reference is detected during encoding.
+ * Circular references cannot be encoded and must be avoided.
+ */
+export declare class E_CIRCULAR_REFERENCE extends BaseException {
+    static status: number;
+    static code: string;
+    /**
+     * Creates a new E_CIRCULAR_REFERENCE exception.
+     */
+    constructor();
+}
+/**
+ * Exception thrown when a value with an unknown or unsupported type cannot be decoded.
+ */
+export declare class E_UNDECODABLE_VALUE extends BaseException {
+    static status: number;
+    static code: string;
+    /**
+     * Creates a new E_UNDECODABLE_VALUE exception.
+     *
+     * @param type - The type string that could not be decoded.
+     */
+    constructor(type: string);
+}
+/**
+ * Exception thrown when attempting to decode a value that is not a valid encoded value.
+ * This indicates the input string is not in the expected encoded format.
+ */
+export declare class E_NOT_AN_ENCODED_VALUE extends BaseException {
+    static status: number;
+    static code: string;
+    /**
+     * Creates a new E_NOT_AN_ENCODED_VALUE exception.
+     *
+     * @param value - The string value that is not a valid encoded value.
+     */
+    constructor(value: string);
+}
+/**
+ * Exception thrown when an invalid version string is encountered.
+ */
+export declare class E_INVALID_VERSION extends BaseException {
+    static status: number;
+    static code: string;
+    /**
+     * Creates a new E_INVALID_VERSION exception.
+     *
+     * @param version - The invalid version string.
+     */
+    constructor(version: string);
+}
+/**
+ * Exception thrown when attempting to decode data encoded with an incompatible version.
+ * This typically occurs when the encoded data is from a newer version than the decoder supports.
+ */
+export declare class E_INCOMPATIBLE_VERSION extends BaseException {
+    static status: number;
+    static code: string;
+    static help: string;
+    /**
+     * Creates a new E_INCOMPATIBLE_VERSION exception.
+     *
+     * @param version - The incompatible version string from the encoded data.
+     */
+    constructor(version: string);
+}

package/private/function_serializer.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Type definition for a dehydrated function value
+ */
+export type DehydratedFunctionValue = {
+    _encodedType: 'function';
+    _encodedValueType: 'string';
+    _encodedValue: string;
+    _namedBindings?: Record<string, any>;
+};
+/**
+ * A portable function serializer that can dehydrate and rehydrate functions
+ * from strings, with support for named bindings and various function types.
+ */
+export declare class FunctionSerializer {
+    #private;
+    /**
+     * Private constructor - use static methods instead
+     */
+    private constructor();
+    /**
+     * Check if a value can be serialized as a function
+     */
+    static canSerialize(value: any): boolean;
+    /**
+     * Dehydrate a function into a serializable format
+     */
+    static dehydrate(fn: Function, namedBindings?: Record<string, any>): DehydratedFunctionValue;
+    /**
+     * Rehydrate a function from its dehydrated format or raw function string
+     */
+    static rehydrate<T extends (...args: any[]) => any>(input: DehydratedFunctionValue | string, namedBindings?: Record<string, any>): T;
+}

package/private/schemas.d.ts

@@ -0,0 +1,27 @@
+export declare const stringSchema: import("@nhtio/validation").StringSchema<string>;
+export declare const numberSchema: import("@nhtio/validation").AlternativesSchema<any>;
+export declare const booleanSchema: import("@nhtio/validation").BooleanSchema<boolean>;
+export declare const bigintSchema: import("@nhtio/validation").AnySchema<any>;
+export declare const nullSchema: import("@nhtio/validation").AnySchema<any>;
+export declare const undefinedSchema: import("@nhtio/validation").AnySchema<any>;
+export declare const primitiveSchema: import("@nhtio/validation").AlternativesSchema<any>;
+export declare const int8ArraySchema: import("@nhtio/validation").AnySchema<any>;
+export declare const uint8ArraySchema: import("@nhtio/validation").AnySchema<any>;
+export declare const uint8ClampedArraySchema: import("@nhtio/validation").AnySchema<any>;
+export declare const int16ArraySchema: import("@nhtio/validation").AnySchema<any>;
+export declare const uint16ArraySchema: import("@nhtio/validation").AnySchema<any>;
+export declare const int32ArraySchema: import("@nhtio/validation").AnySchema<any>;
+export declare const uint32ArraySchema: import("@nhtio/validation").AnySchema<any>;
+export declare const float32ArraySchema: import("@nhtio/validation").AnySchema<any>;
+export declare const float64ArraySchema: import("@nhtio/validation").AnySchema<any>;
+export declare const bigInt64ArraySchema: import("@nhtio/validation").AnySchema<any>;
+export declare const bigUint64ArraySchema: import("@nhtio/validation").AnySchema<any>;
+export declare const typedArraySchema: import("@nhtio/validation").AlternativesSchema<any>;
+export declare const bigIntTypedArraySchema: import("@nhtio/validation").AlternativesSchema<any>;
+export declare const dateSchema: import("@nhtio/validation").AnySchema<any>;
+export declare const regExpSchema: import("@nhtio/validation").AnySchema<any>;
+export declare const arrayBufferSchema: import("@nhtio/validation").AnySchema<any>;
+export declare const dataViewSchema: import("@nhtio/validation").AnySchema<any>;
+export declare const errorSchema: import("@nhtio/validation").AnySchema<any>;
+export declare const uniterableObjectSchema: import("@nhtio/validation").AlternativesSchema<any>;
+export declare const phoneObjectSchema: import("@nhtio/validation").AlternativesSchema<any>;

package/private/stringification.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Converts a string into a compressed base64 string
+ * @param data The string to be converted into a compressed base64 string
+ * @returns The compressed base64 string
+ */
+export declare const utoa: (data: string) => string;
+/**
+ * Converts a compressed base64 string back into a normal string
+ * @param base64 The compressed base64 string to be converted back into a normal string
+ * @returns The normal string
+ */
+export declare const atou: (base64: string) => string;

package/private/structured_data.d.ts

@@ -0,0 +1,10 @@
+import type { Encodable } from './types';
+import type { SerializedRecord } from '@ungap/structured-clone';
+export interface StructuredDataObject {
+    _t: string;
+    _s: {
+        [key: string]: StructuredDataObject;
+    } | StructuredDataObject | StructuredDataObject[] | [StructuredDataObject, StructuredDataObject][] | SerializedRecord | string;
+}
+export declare const toStructuredData: (value: Encodable, seen?: WeakSet<any>) => StructuredDataObject;
+export declare const fromStructuredData: <T extends Encodable = Encodable>(data: StructuredDataObject) => T;

package/private/type_guards.d.ts

@@ -0,0 +1,59 @@
+import { DateTime, Duration, Interval, SystemZone } from 'luxon';
+import type { Phone } from '@nhtio/phone-object';
+/**
+ * Type guard to check if a value is a plain object (not null, not array)
+ * @param value - The value to check
+ * @returns True if the value is a plain object, false otherwise
+ */
+export declare const isObject: (value: unknown) => value is {
+    [key: string]: unknown;
+};
+/**
+ * Type guard to check if a value is an array
+ * @param value - The value to check
+ * @returns True if the value is an array, false otherwise
+ */
+export declare const isArray: (value: unknown) => value is unknown[];
+/**
+ * Type guard to check if a value is a Luxon DateTime instance
+ * @param value - The value to check
+ * @returns True if the value is a Luxon DateTime, false otherwise
+ */
+export declare const isLuxonDateTime: (value: unknown) => value is DateTime;
+/**
+ * Type guard to check if a value is a Luxon Duration instance
+ * @param value - The value to check
+ * @returns True if the value is a Luxon Duration, false otherwise
+ */
+export declare const isLuxonDuration: (value: unknown) => value is Duration;
+/**
+ * Type guard to check if a value is a Luxon Interval instance
+ * @param value - The value to check
+ * @returns True if the value is a Luxon Interval, false otherwise
+ */
+export declare const isLuxonInterval: (value: unknown) => value is Interval;
+/**
+ * Type guard to check if a value is a valid Lucid binary value (Uint8Array or Buffer)
+ * @param value - The value to check
+ * @returns True if the value is a LucidBinaryValue, false otherwise
+ */
+export declare const isLucidBinaryValue: (value: unknown) => value is Uint8Array | Buffer;
+/**
+ * Checks if a value is an instance of a specific class.
+ * @param value - The value to check
+ * @param type - The name of the class to check against
+ * @returns true if the value is an instance of the specified class, false otherwise
+ */
+export declare const isInstanceOf: <T>(value: unknown, type: string, ctor?: new (...args: any[]) => T) => value is T;
+export declare const isMap: <K = any, T = any>(value: unknown) => value is Map<K, T>;
+export declare const isSet: <T = any>(value: unknown) => value is Set<T>;
+export declare const isNumber: (value: unknown) => value is number;
+export declare const isNegativeZero: (value: unknown) => value is -0;
+export declare const isError: (value: unknown) => value is Error;
+export declare const isTypedArray: (value: unknown) => value is Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array;
+export declare const isBigIntTypedArray: (value: unknown) => value is BigInt64Array | BigUint64Array;
+export declare const isUniterableObject: (value: unknown) => value is Date | RegExp | ArrayBuffer | DataView | Error;
+export declare const isPrimitive: (value: unknown) => value is string | number | boolean | bigint | null;
+export declare const isPhoneObject: (value: unknown) => value is Phone;
+export declare const isLuxonSystemZone: (value: unknown) => value is SystemZone;
+export declare const isBigInt: (value: unknown) => value is bigint;

package/private/types.d.ts

@@ -0,0 +1,16 @@
+import type { Phone } from '@nhtio/phone-object';
+import type { DateTime, Duration, Interval } from 'luxon';
+/**
+ * Defines the union of all encodable primitive types.
+ */
+export type EncodablePrimitive = string | number | boolean | bigint | null | undefined;
+/**
+ * Defines a union for all the encodable typed arrays.
+ */
+export type EncodableTypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array;
+/**
+ * Defines all the types which can be be encoded
+ */
+export type Encodable = EncodablePrimitive | Date | RegExp | ArrayBuffer | DataView | DateTime | Duration | Interval | EncodableTypedArray | Encodable[] | {
+    [key: string]: Encodable;
+} | Map<Encodable, Encodable> | Set<Encodable> | Error | EvalError | RangeError | ReferenceError | SyntaxError | TypeError | URIError | Phone | Function | ((...args: any[]) => any);

package/types.cjs

@@ -0,0 +1,2 @@
+"use strict";
+//# sourceMappingURL=types.cjs.map

package/types.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/types.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Types used by the encoder/decoder
+ * @module @nhtio/encoder/types
+ */
+export type { BaseException } from './private/exceptions';
+export type { E_NOT_AN_ENCODED_VALUE, E_INVALID_VERSION, E_INCOMPATIBLE_VERSION, E_ENCODING_FAILED, E_CIRCULAR_REFERENCE, E_UNENCODABLE_VALUE, E_UNDECODABLE_VALUE, } from './private/exceptions';
+export type { Encodable, EncodablePrimitive, EncodableTypedArray } from './private/types';
+export type { Phone } from '@nhtio/phone-object';
+export type { DateTime, Duration, Interval } from 'luxon';

package/types.mjs

@@ -0,0 +1,2 @@
+
+//# sourceMappingURL=types.mjs.map

package/types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":""}