crous 1.0.0

package/index.d.ts

@@ -0,0 +1,358 @@
+/**
+ * Crous - High-performance binary serialization for Node.js
+ * 
+ * TypeScript type definitions for the Crous serialization library.
+ * 
+ * @packageDocumentation
+ */
+
+/**
+ * Custom error class for Crous-related errors
+ */
+export class CrousError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Error thrown during encoding/serialization
+ */
+export class CrousEncodeError extends CrousError {
+    constructor(message: string);
+}
+
+/**
+ * Error thrown during decoding/deserialization
+ */
+export class CrousDecodeError extends CrousError {
+    constructor(message: string);
+}
+
+/**
+ * Function type for custom serializers
+ * @template T - The type being serialized
+ */
+export type SerializerFunction<T = any> = (obj: T) => any;
+
+/**
+ * Function type for custom decoders
+ * @template T - The type being deserialized
+ */
+export type DecoderFunction<T = any> = (value: any) => T;
+
+/**
+ * Function type for object hooks (post-processing dictionaries)
+ */
+export type ObjectHook = (obj: Record<string, any>) => any;
+
+/**
+ * Function type for default serializer fallback
+ */
+export type DefaultFunction = (obj: any) => any;
+
+/**
+ * Options for dumps() function
+ */
+export interface DumpsOptions {
+    /**
+     * Optional function to handle custom types that aren't natively supported
+     */
+    default?: DefaultFunction;
+    
+    /**
+     * Whether to allow custom serializers (default: true)
+     */
+    allowCustom?: boolean;
+}
+
+/**
+ * Options for loads() function
+ */
+export interface LoadsOptions {
+    /**
+     * Optional function to post-process dictionary objects during deserialization
+     */
+    objectHook?: ObjectHook;
+}
+
+/**
+ * Options for dump() function
+ */
+export interface DumpOptions extends DumpsOptions {
+}
+
+/**
+ * Options for load() function
+ */
+export interface LoadOptions extends LoadsOptions {
+}
+
+/**
+ * Encoder class for custom serialization control
+ */
+export class CrousEncoder {
+    /**
+     * Create a new encoder instance
+     * @param options - Encoder options
+     */
+    constructor(options?: {
+        default?: DefaultFunction;
+        allowCustom?: boolean;
+    });
+    
+    /**
+     * Encode an object to binary format
+     * @param obj - The object to encode
+     * @returns Binary encoded data
+     */
+    encode(obj: any): Buffer;
+}
+
+/**
+ * Decoder class for custom deserialization control
+ */
+export class CrousDecoder {
+    /**
+     * Create a new decoder instance
+     * @param options - Decoder options
+     */
+    constructor(options?: {
+        objectHook?: ObjectHook;
+    });
+    
+    /**
+     * Decode binary data to an object
+     * @param data - The binary data to decode
+     * @returns Deserialized object
+     */
+    decode(data: Buffer): any;
+}
+
+/**
+ * Version information structure
+ */
+export interface VersionInfo {
+    major: number;
+    minor: number;
+    patch: number;
+    string: string;
+    tuple: [number, number, number];
+    hex: number;
+}
+
+/**
+ * Serialize a JavaScript value to binary format
+ * 
+ * @param obj - The object to serialize
+ * @param options - Serialization options
+ * @returns Binary encoded data as a Buffer
+ * @throws {CrousEncodeError} If encoding fails
+ * 
+ * @example
+ * ```typescript
+ * import { dumps } from 'crous';
+ * 
+ * const data = { name: 'Alice', age: 30 };
+ * const binary = dumps(data);
+ * console.log(binary); // <Buffer ...>
+ * ```
+ */
+export function dumps(obj: any, options?: DumpsOptions): Buffer;
+
+/**
+ * Deserialize binary data to a JavaScript value
+ * 
+ * @param data - Binary data to deserialize
+ * @param options - Deserialization options
+ * @returns Deserialized JavaScript value
+ * @throws {CrousDecodeError} If decoding fails
+ * 
+ * @example
+ * ```typescript
+ * import { loads, dumps } from 'crous';
+ * 
+ * const binary = dumps({ name: 'Alice' });
+ * const data = loads(binary);
+ * console.log(data); // { name: 'Alice' }
+ * ```
+ */
+export function loads(data: Buffer, options?: LoadsOptions): any;
+
+/**
+ * Serialize a JavaScript value and write to a file
+ * 
+ * @param obj - The object to serialize
+ * @param filepath - Path to the output file or writable stream
+ * @param options - Serialization options
+ * @throws {CrousEncodeError} If encoding fails
+ * 
+ * @example
+ * ```typescript
+ * import { dump } from 'crous';
+ * import * as fs from 'fs';
+ * 
+ * const data = { name: 'Alice', age: 30 };
+ * 
+ * // Write to file path
+ * dump(data, 'output.crous');
+ * 
+ * // Write to stream
+ * const stream = fs.createWriteStream('output.crous');
+ * dump(data, stream);
+ * ```
+ */
+export function dump(obj: any, filepath: string | NodeJS.WritableStream, options?: DumpOptions): void;
+
+/**
+ * Deserialize a JavaScript value from a file
+ * 
+ * @param filepath - Path to the input file or readable stream
+ * @param options - Deserialization options
+ * @returns Deserialized JavaScript value
+ * @throws {CrousDecodeError} If decoding fails
+ * 
+ * @example
+ * ```typescript
+ * import { load } from 'crous';
+ * import * as fs from 'fs';
+ * 
+ * // Read from file path
+ * const data = load('input.crous');
+ * 
+ * // Read from stream
+ * const stream = fs.createReadStream('input.crous');
+ * const data2 = load(stream);
+ * ```
+ */
+export function load(filepath: string | NodeJS.ReadableStream, options?: LoadOptions): any;
+
+/**
+ * Register a custom serializer for a specific type
+ * 
+ * @param type - The constructor/class to register a serializer for
+ * @param serializer - Function to convert instances to serializable values
+ * @throws {TypeError} If serializer is not a function
+ * 
+ * @example
+ * ```typescript
+ * import { registerSerializer, dumps } from 'crous';
+ * 
+ * class Point {
+ *     constructor(public x: number, public y: number) {}
+ * }
+ * 
+ * registerSerializer(Point, (point) => {
+ *     return { x: point.x, y: point.y };
+ * });
+ * 
+ * const binary = dumps(new Point(10, 20));
+ * ```
+ */
+export function registerSerializer<T = any>(
+    type: new (...args: any[]) => T,
+    serializer: SerializerFunction<T>
+): void;
+
+/**
+ * Unregister a custom serializer for a specific type
+ * 
+ * @param type - The constructor/class to unregister
+ * 
+ * @example
+ * ```typescript
+ * import { unregisterSerializer } from 'crous';
+ * 
+ * class Point {}
+ * unregisterSerializer(Point);
+ * ```
+ */
+export function unregisterSerializer<T = any>(
+    type: new (...args: any[]) => T
+): void;
+
+/**
+ * Register a custom decoder for a specific tag
+ * 
+ * @param tag - The tag identifier (integer)
+ * @param decoder - Function to convert tagged values to objects
+ * @throws {TypeError} If decoder is not a function
+ * 
+ * @example
+ * ```typescript
+ * import { registerDecoder, loads } from 'crous';
+ * 
+ * class Point {
+ *     constructor(public x: number, public y: number) {}
+ * }
+ * 
+ * registerDecoder(100, (value) => {
+ *     return new Point(value.x, value.y);
+ * });
+ * 
+ * const data = loads(binary);
+ * ```
+ */
+export function registerDecoder<T = any>(
+    tag: number,
+    decoder: DecoderFunction<T>
+): void;
+
+/**
+ * Unregister a custom decoder for a specific tag
+ * 
+ * @param tag - The tag identifier to unregister
+ * 
+ * @example
+ * ```typescript
+ * import { unregisterDecoder } from 'crous';
+ * 
+ * unregisterDecoder(100);
+ * ```
+ */
+export function unregisterDecoder(tag: number): void;
+
+/**
+ * Get version information about the Crous library
+ * 
+ * @returns Version information object
+ * 
+ * @example
+ * ```typescript
+ * import { versionInfo } from 'crous';
+ * 
+ * const info = versionInfo();
+ * console.log(`Crous v${info.string}`);
+ * ```
+ */
+export function versionInfo(): VersionInfo;
+
+/**
+ * Module version string
+ */
+export const version: string;
+
+/**
+ * Module version tuple [major, minor, patch]
+ */
+export const versionTuple: [number, number, number];
+
+// Re-export as default for CommonJS compatibility
+declare const crous: {
+    dumps: typeof dumps;
+    loads: typeof loads;
+    dump: typeof dump;
+    load: typeof load;
+    registerSerializer: typeof registerSerializer;
+    unregisterSerializer: typeof unregisterSerializer;
+    registerDecoder: typeof registerDecoder;
+    unregisterDecoder: typeof unregisterDecoder;
+    versionInfo: typeof versionInfo;
+    CrousEncoder: typeof CrousEncoder;
+    CrousDecoder: typeof CrousDecoder;
+    CrousError: typeof CrousError;
+    CrousEncodeError: typeof CrousEncodeError;
+    CrousDecodeError: typeof CrousDecodeError;
+    version: string;
+    versionTuple: [number, number, number];
+};
+
+export default crous;

package/index.js

@@ -0,0 +1,290 @@
+/**
+ * Crous - High-performance binary serialization for Node.js
+ * 
+ * This module provides complete Crous serialization with full support
+ * for Node.js native types and custom serializers.
+ * 
+ * @module crous
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// Load native addon
+let native;
+try {
+    native = require('./build/Release/crous.node');
+} catch (e) {
+    try {
+        native = require('./build/Debug/crous.node');
+    } catch (e2) {
+        throw new Error('Could not load Crous native addon. Please run: npm install');
+    }
+}
+
+// Version information
+const VERSION = {
+    major: 1,
+    minor: 0,
+    patch: 0,
+    get string() {
+        return `${this.major}.${this.minor}.${this.patch}`;
+    },
+    get tuple() {
+        return [this.major, this.minor, this.patch];
+    },
+    get hex() {
+        return (this.major << 16) | (this.minor << 8) | this.patch;
+    }
+};
+
+/**
+ * Custom error classes
+ */
+class CrousError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CrousError';
+    }
+}
+
+class CrousEncodeError extends CrousError {
+    constructor(message) {
+        super(message);
+        this.name = 'CrousEncodeError';
+    }
+}
+
+class CrousDecodeError extends CrousError {
+    constructor(message) {
+        super(message);
+        this.name = 'CrousDecodeError';
+    }
+}
+
+/**
+ * Encoder class for custom serialization control
+ */
+class CrousEncoder {
+    constructor(options = {}) {
+        this.default = options.default || null;
+        this.allowCustom = options.allowCustom !== false;
+    }
+    
+    encode(obj) {
+        return native.dumps(obj, this.default);
+    }
+}
+
+/**
+ * Decoder class for custom deserialization control
+ */
+class CrousDecoder {
+    constructor(options = {}) {
+        this.objectHook = options.objectHook || null;
+    }
+    
+    decode(data) {
+        return native.loads(data, this.objectHook);
+    }
+}
+
+/**
+ * Serialize a JavaScript value to binary format
+ * 
+ * @param {*} obj - The object to serialize
+ * @param {Object} options - Serialization options
+ * @param {Function} options.default - Optional function for custom types
+ * @param {boolean} options.allowCustom - Whether to allow custom serializers
+ * @returns {Buffer} Binary encoded data
+ * @throws {CrousEncodeError} If encoding fails
+ */
+function dumps(obj, options = {}) {
+    try {
+        return native.dumps(obj, options.default || null);
+    } catch (error) {
+        throw new CrousEncodeError(error.message);
+    }
+}
+
+/**
+ * Deserialize binary data to a JavaScript value
+ * 
+ * @param {Buffer} data - Binary data to deserialize
+ * @param {Object} options - Deserialization options
+ * @param {Function} options.objectHook - Optional function for post-processing objects
+ * @returns {*} Deserialized JavaScript value
+ * @throws {CrousDecodeError} If decoding fails
+ */
+function loads(data, options = {}) {
+    try {
+        if (!Buffer.isBuffer(data)) {
+            data = Buffer.from(data);
+        }
+        return native.loads(data, options.objectHook || null);
+    } catch (error) {
+        throw new CrousDecodeError(error.message);
+    }
+}
+
+/**
+ * Serialize a JavaScript value and write to a file
+ * 
+ * @param {*} obj - The object to serialize
+ * @param {string|stream.Writable} filepath - Path to output file or writable stream
+ * @param {Object} options - Serialization options
+ * @throws {CrousEncodeError} If encoding fails
+ */
+function dump(obj, filepath, options = {}) {
+    try {
+        const binary = native.dumps(obj, options.default || null);
+        
+        if (typeof filepath === 'string') {
+            // Write to file path
+            fs.writeFileSync(filepath, binary);
+        } else if (filepath && typeof filepath.write === 'function') {
+            // Write to stream
+            filepath.write(binary);
+        } else {
+            throw new Error('filepath must be a string or writable stream');
+        }
+    } catch (error) {
+        if (error instanceof CrousEncodeError) {
+            throw error;
+        }
+        throw new CrousEncodeError(error.message);
+    }
+}
+
+/**
+ * Deserialize a JavaScript value from a file
+ * 
+ * @param {string|stream.Readable} filepath - Path to input file or readable stream
+ * @param {Object} options - Deserialization options
+ * @returns {*} Deserialized JavaScript value
+ * @throws {CrousDecodeError} If decoding fails
+ */
+function load(filepath, options = {}) {
+    try {
+        let binary;
+        
+        if (typeof filepath === 'string') {
+            // Read from file path
+            binary = fs.readFileSync(filepath);
+        } else if (filepath && typeof filepath.read === 'function') {
+            // Read from stream
+            const chunks = [];
+            let chunk;
+            while ((chunk = filepath.read()) !== null) {
+                chunks.push(chunk);
+            }
+            binary = Buffer.concat(chunks);
+        } else {
+            throw new Error('filepath must be a string or readable stream');
+        }
+        
+        return native.loads(binary, options.objectHook || null);
+    } catch (error) {
+        if (error instanceof CrousDecodeError) {
+            throw error;
+        }
+        throw new CrousDecodeError(error.message);
+    }
+}
+
+/**
+ * Register a custom serializer for a specific type
+ * 
+ * @param {Function} type - The constructor/class to register a serializer for
+ * @param {Function} serializer - Function to convert instances to serializable values
+ * @throws {TypeError} If serializer is not a function
+ */
+function registerSerializer(type, serializer) {
+    if (typeof serializer !== 'function') {
+        throw new TypeError('Serializer must be a function');
+    }
+    native.registerSerializer(type, serializer);
+}
+
+/**
+ * Unregister a custom serializer for a specific type
+ * 
+ * @param {Function} type - The constructor/class to unregister
+ */
+function unregisterSerializer(type) {
+    native.unregisterSerializer(type);
+}
+
+/**
+ * Register a custom decoder for a specific tag
+ * 
+ * @param {number} tag - The tag identifier (integer)
+ * @param {Function} decoder - Function to convert tagged values to objects
+ * @throws {TypeError} If decoder is not a function
+ */
+function registerDecoder(tag, decoder) {
+    if (typeof decoder !== 'function') {
+        throw new TypeError('Decoder must be a function');
+    }
+    native.registerDecoder(tag, decoder);
+}
+
+/**
+ * Unregister a custom decoder for a specific tag
+ * 
+ * @param {number} tag - The tag identifier to unregister
+ */
+function unregisterDecoder(tag) {
+    native.unregisterDecoder(tag);
+}
+
+/**
+ * Get version information about the Crous library
+ * 
+ * @returns {Object} Version information object
+ */
+function versionInfo() {
+    return {
+        major: VERSION.major,
+        minor: VERSION.minor,
+        patch: VERSION.patch,
+        string: VERSION.string,
+        tuple: VERSION.tuple,
+        hex: VERSION.hex
+    };
+}
+
+// Export all functions and classes
+module.exports = {
+    // Core functions
+    dumps,
+    loads,
+    dump,
+    load,
+    
+    // Custom serializers/decoders
+    registerSerializer,
+    unregisterSerializer,
+    registerDecoder,
+    unregisterDecoder,
+    
+    // Classes
+    CrousEncoder,
+    CrousDecoder,
+    CrousError,
+    CrousEncodeError,
+    CrousDecodeError,
+    
+    // Version info
+    versionInfo,
+    version: VERSION.string,
+    versionTuple: VERSION.tuple,
+};
+
+// ES6 named exports for modern Node.js
+if (typeof exports !== 'undefined') {
+    Object.defineProperty(exports, "__esModule", { value: true });
+    exports.default = module.exports;
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "crous",
+  "version": "1.0.0",
+  "description": "Crous: High-performance binary serialization format for Node.js",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "keywords": [
+    "serialization",
+    "binary",
+    "encoding",
+    "decoding",
+    "msgpack",
+    "protobuf",
+    "fast",
+    "native",
+    "performance"
+  ],
+  "author": "Pawan Kumar <aegis.invincible@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/axiomchronicles/crous.git"
+  },
+  "bugs": {
+    "url": "https://github.com/axiomchronicles/crous/issues"
+  },
+  "homepage": "https://github.com/axiomchronicles/crous#readme",
+  "scripts": {
+    "install": "node-gyp rebuild",
+    "build": "node-gyp rebuild",
+    "test": "node test/test_basic.js && node test/test_advanced.js",
+    "test:basic": "node test/test_basic.js",
+    "test:advanced": "node test/test_advanced.js",
+    "test:performance": "node test/test_performance.js",
+    "test:compat": "node test/test_python_compat.js",
+    "test:all": "npm run test:basic && npm run test:advanced && npm run test:performance && npm run test:compat",
+    "clean": "node-gyp clean"
+  },
+  "gypfile": true,
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "dependencies": {
+    "node-addon-api": "^8.0.0"
+  },
+  "devDependencies": {
+    "node-gyp": "^10.0.0"
+  },
+  "files": [
+    "binding.gyp",
+    "index.js",
+    "index.d.ts",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ]
+}