tersejson 0.1.0

package/dist/types-CzaGQaV7.d.mts

@@ -0,0 +1,134 @@
+/**
+ * TerseJSON Types
+ *
+ * Defines the wire format and configuration options for transparent
+ * JSON key compression.
+ */
+/**
+ * The compressed format sent over the wire
+ */
+interface TersePayload<T = unknown> {
+    /** Marker to identify this as a TerseJSON payload */
+    __terse__: true;
+    /** Version for future compatibility */
+    v: 1;
+    /** Key mapping: short key -> original key */
+    k: Record<string, string>;
+    /** The compressed data with short keys */
+    d: T;
+    /** Pattern used for key generation (for debugging/info) */
+    p?: string;
+}
+/**
+ * Built-in key pattern presets
+ */
+type KeyPatternPreset = 'alpha' | 'numeric' | 'alphanumeric' | 'short' | 'prefixed';
+/**
+ * Custom key generator function
+ */
+type KeyGenerator = (index: number) => string;
+/**
+ * Key pattern configuration
+ */
+type KeyPattern = KeyPatternPreset | {
+    prefix: string;
+    style?: 'numeric' | 'alpha';
+} | KeyGenerator;
+/**
+ * How to handle nested structures
+ */
+type NestedHandling = 'deep' | 'shallow' | 'arrays' | number;
+/**
+ * Compression options
+ */
+interface CompressOptions {
+    /**
+     * Minimum key length to consider for compression
+     * Keys shorter than this won't be shortened
+     * @default 3
+     */
+    minKeyLength?: number;
+    /**
+     * Maximum depth to traverse for nested objects
+     * @default 10
+     */
+    maxDepth?: number;
+    /**
+     * Key pattern to use for generating short keys
+     * @default 'alpha'
+     */
+    keyPattern?: KeyPattern;
+    /**
+     * How to handle nested objects and arrays
+     * @default 'deep'
+     */
+    nestedHandling?: NestedHandling;
+    /**
+     * Only compress keys that appear in all objects (homogeneous)
+     * @default false
+     */
+    homogeneousOnly?: boolean;
+    /**
+     * Keys to always exclude from compression
+     */
+    excludeKeys?: string[];
+    /**
+     * Keys to always include in compression (even if short)
+     */
+    includeKeys?: string[];
+}
+/**
+ * Configuration options for the Express middleware
+ */
+interface TerseMiddlewareOptions extends CompressOptions {
+    /**
+     * Minimum array length to trigger compression
+     * @default 2
+     */
+    minArrayLength?: number;
+    /**
+     * Custom function to determine if a response should be compressed
+     * Return false to skip compression for specific responses
+     */
+    shouldCompress?: (data: unknown, req: unknown) => boolean;
+    /**
+     * Custom header name for signaling terse responses
+     * @default 'x-terse-json'
+     */
+    headerName?: string;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Configuration options for the client
+ */
+interface TerseClientOptions {
+    /**
+     * Custom header name to check for terse responses
+     * @default 'x-terse-json'
+     */
+    headerName?: string;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Automatically expand terse responses
+     * @default true
+     */
+    autoExpand?: boolean;
+}
+/**
+ * Type helper to preserve original types through compression
+ */
+type Tersed<T> = T;
+/**
+ * Check if a value is a TersePayload
+ */
+declare function isTersePayload(value: unknown): value is TersePayload;
+
+export { type CompressOptions as C, type KeyPattern as K, type NestedHandling as N, type TersePayload as T, type TerseMiddlewareOptions as a, type TerseClientOptions as b, type KeyPatternPreset as c, type KeyGenerator as d, type Tersed as e, isTersePayload as i };

package/dist/types-CzaGQaV7.d.ts

@@ -0,0 +1,134 @@
+/**
+ * TerseJSON Types
+ *
+ * Defines the wire format and configuration options for transparent
+ * JSON key compression.
+ */
+/**
+ * The compressed format sent over the wire
+ */
+interface TersePayload<T = unknown> {
+    /** Marker to identify this as a TerseJSON payload */
+    __terse__: true;
+    /** Version for future compatibility */
+    v: 1;
+    /** Key mapping: short key -> original key */
+    k: Record<string, string>;
+    /** The compressed data with short keys */
+    d: T;
+    /** Pattern used for key generation (for debugging/info) */
+    p?: string;
+}
+/**
+ * Built-in key pattern presets
+ */
+type KeyPatternPreset = 'alpha' | 'numeric' | 'alphanumeric' | 'short' | 'prefixed';
+/**
+ * Custom key generator function
+ */
+type KeyGenerator = (index: number) => string;
+/**
+ * Key pattern configuration
+ */
+type KeyPattern = KeyPatternPreset | {
+    prefix: string;
+    style?: 'numeric' | 'alpha';
+} | KeyGenerator;
+/**
+ * How to handle nested structures
+ */
+type NestedHandling = 'deep' | 'shallow' | 'arrays' | number;
+/**
+ * Compression options
+ */
+interface CompressOptions {
+    /**
+     * Minimum key length to consider for compression
+     * Keys shorter than this won't be shortened
+     * @default 3
+     */
+    minKeyLength?: number;
+    /**
+     * Maximum depth to traverse for nested objects
+     * @default 10
+     */
+    maxDepth?: number;
+    /**
+     * Key pattern to use for generating short keys
+     * @default 'alpha'
+     */
+    keyPattern?: KeyPattern;
+    /**
+     * How to handle nested objects and arrays
+     * @default 'deep'
+     */
+    nestedHandling?: NestedHandling;
+    /**
+     * Only compress keys that appear in all objects (homogeneous)
+     * @default false
+     */
+    homogeneousOnly?: boolean;
+    /**
+     * Keys to always exclude from compression
+     */
+    excludeKeys?: string[];
+    /**
+     * Keys to always include in compression (even if short)
+     */
+    includeKeys?: string[];
+}
+/**
+ * Configuration options for the Express middleware
+ */
+interface TerseMiddlewareOptions extends CompressOptions {
+    /**
+     * Minimum array length to trigger compression
+     * @default 2
+     */
+    minArrayLength?: number;
+    /**
+     * Custom function to determine if a response should be compressed
+     * Return false to skip compression for specific responses
+     */
+    shouldCompress?: (data: unknown, req: unknown) => boolean;
+    /**
+     * Custom header name for signaling terse responses
+     * @default 'x-terse-json'
+     */
+    headerName?: string;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Configuration options for the client
+ */
+interface TerseClientOptions {
+    /**
+     * Custom header name to check for terse responses
+     * @default 'x-terse-json'
+     */
+    headerName?: string;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Automatically expand terse responses
+     * @default true
+     */
+    autoExpand?: boolean;
+}
+/**
+ * Type helper to preserve original types through compression
+ */
+type Tersed<T> = T;
+/**
+ * Check if a value is a TersePayload
+ */
+declare function isTersePayload(value: unknown): value is TersePayload;
+
+export { type CompressOptions as C, type KeyPattern as K, type NestedHandling as N, type TersePayload as T, type TerseMiddlewareOptions as a, type TerseClientOptions as b, type KeyPatternPreset as c, type KeyGenerator as d, type Tersed as e, isTersePayload as i };

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "tersejson",
+  "version": "0.1.0",
+  "description": "Transparent JSON key compression for Express APIs. Reduce bandwidth by up to 80% with zero code changes.",
+  "keywords": [
+    "json",
+    "compression",
+    "express",
+    "middleware",
+    "bandwidth",
+    "optimization",
+    "api",
+    "rest",
+    "keys",
+    "minify"
+  ],
+  "author": "Tim Carter",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/timclausendev-web/tersejson"
+  },
+  "homepage": "https://tersejson.com",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./express": {
+      "types": "./dist/express.d.ts",
+      "import": "./dist/express.mjs",
+      "require": "./dist/express.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.mjs",
+      "require": "./dist/client.js"
+    },
+    "./integrations": {
+      "types": "./dist/integrations.d.ts",
+      "import": "./dist/integrations.mjs",
+      "require": "./dist/integrations.js"
+    },
+    "./analytics": {
+      "types": "./dist/analytics.d.ts",
+      "import": "./dist/analytics.mjs",
+      "require": "./dist/analytics.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.11.0",
+    "eslint": "^8.56.0",
+    "express": "^4.18.2",
+    "sharp": "^0.34.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.0"
+  },
+  "peerDependencies": {
+    "express": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}