brevit 0.1.1

package/TYPESCRIPT.md

@@ -0,0 +1,230 @@
+# TypeScript Support for Brevit.js
+
+Brevit.js includes comprehensive TypeScript definitions for full type safety and excellent IDE support.
+
+## Installation
+
+No additional installation required! TypeScript definitions are included in the package.
+
+```bash
+npm install brevit-js
+```
+
+## Basic Usage
+
+```typescript
+import {
+  BrevitClient,
+  BrevitConfig,
+  JsonOptimizationMode,
+} from 'brevit-js';
+
+const config = new BrevitConfig({
+  jsonMode: JsonOptimizationMode.Flatten,
+});
+
+const client = new BrevitClient(config);
+const optimized = await client.optimize({ user: { name: 'John' } });
+```
+
+## Type Exports
+
+All types are exported for your convenience:
+
+### Enums
+
+```typescript
+import {
+  JsonOptimizationMode,
+  TextOptimizationMode,
+  ImageOptimizationMode,
+} from 'brevit-js';
+
+// Usage
+const mode: typeof JsonOptimizationMode.Flatten = JsonOptimizationMode.Flatten;
+```
+
+### Type Aliases
+
+```typescript
+import type {
+  JsonOptimizationModeType,
+  TextOptimizationModeType,
+  ImageOptimizationModeType,
+} from 'brevit-js';
+
+function setMode(mode: JsonOptimizationModeType) {
+  // Type-safe mode setting
+}
+```
+
+### Interfaces
+
+```typescript
+import type {
+  BrevitConfigOptions,
+  BrevitClientOptions,
+  TextOptimizerFunction,
+  ImageOptimizerFunction,
+} from 'brevit-js';
+
+// Configuration options
+const config: BrevitConfigOptions = {
+  jsonMode: JsonOptimizationMode.Flatten,
+  longTextThreshold: 1000,
+};
+
+// Custom optimizer functions
+const textOptimizer: TextOptimizerFunction = async (text, intent) => {
+  // Your implementation
+  return optimizedText;
+};
+```
+
+## Examples
+
+### Example 1: Type-Safe Configuration
+
+```typescript
+import {
+  BrevitClient,
+  BrevitConfig,
+  JsonOptimizationMode,
+  type BrevitConfigOptions,
+} from 'brevit-js';
+
+const configOptions: BrevitConfigOptions = {
+  jsonMode: JsonOptimizationMode.Flatten,
+  textMode: 'Clean',
+  imageMode: 'Ocr',
+  jsonPathsToKeep: ['user.name', 'order.orderId'],
+  longTextThreshold: 1000,
+};
+
+const config = new BrevitConfig(configOptions);
+const client = new BrevitClient(config);
+```
+
+### Example 2: Custom Optimizers with Types
+
+```typescript
+import {
+  BrevitClient,
+  BrevitConfig,
+  type TextOptimizerFunction,
+  type ImageOptimizerFunction,
+} from 'brevit-js';
+
+const customTextOptimizer: TextOptimizerFunction = async (longText, intent) => {
+  const response = await fetch('/api/summarize', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ text: longText, intent }),
+  });
+  const { summary } = await response.json();
+  return summary;
+};
+
+const customImageOptimizer: ImageOptimizerFunction = async (imageData, intent) => {
+  const base64 = btoa(String.fromCharCode(...new Uint8Array(imageData)));
+  const response = await fetch('/api/ocr', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ image: base64 }),
+  });
+  const { text } = await response.json();
+  return text;
+};
+
+const client = new BrevitClient(new BrevitConfig(), {
+  textOptimizer: customTextOptimizer,
+  imageOptimizer: customImageOptimizer,
+});
+```
+
+### Example 3: Type-Safe Data Structures
+
+```typescript
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+interface Order {
+  orderId: string;
+  status: string;
+  items: Array<{
+    sku: string;
+    name: string;
+    quantity: number;
+  }>;
+}
+
+const user: User = {
+  id: 'u-123',
+  name: 'Javian',
+  email: 'support@javianpicardo.com',
+};
+
+const order: Order = {
+  orderId: 'o-456',
+  status: 'SHIPPED',
+  items: [
+    { sku: 'A-88', name: 'Brevit Pro License', quantity: 1 },
+  ],
+};
+
+const client = new BrevitClient();
+const optimizedUser = await client.optimize(user);
+const optimizedOrder = await client.optimize(order);
+// Both return Promise<string>
+```
+
+### Example 4: Generic Helper Function
+
+```typescript
+import { BrevitClient, BrevitConfig } from 'brevit-js';
+
+async function optimizeData<T>(data: T): Promise<string> {
+  const client = new BrevitClient();
+  return await client.optimize(data);
+}
+
+const result = await optimizeData({ name: 'John', age: 30 });
+```
+
+## IDE Support
+
+With TypeScript definitions, you get:
+
+- ✅ **Autocomplete**: Full IntelliSense support in VS Code, WebStorm, etc.
+- ✅ **Type Checking**: Catch errors at compile time
+- ✅ **Refactoring**: Safe refactoring with type-aware tools
+- ✅ **Documentation**: Hover to see JSDoc comments
+- ✅ **Navigation**: Jump to definitions and find references
+
+## Type Checking
+
+Enable strict type checking in your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true
+  }
+}
+```
+
+## Compatibility
+
+- **TypeScript**: 4.5+
+- **Node.js**: 18.x, 20.x
+- **Browsers**: Modern browsers with ES2020 support
+
+## Contributing
+
+When contributing to Brevit.js, ensure TypeScript definitions stay in sync with the JavaScript implementation. The definitions file is located at `src/brevit.d.ts`.
+

package/example.ts

@@ -0,0 +1,139 @@
+/**
+ * TypeScript usage example for Brevit.js
+ */
+
+import {
+  BrevitClient,
+  BrevitConfig,
+  JsonOptimizationMode,
+  TextOptimizationMode,
+  ImageOptimizationMode,
+  type BrevitConfigOptions,
+  type TextOptimizerFunction,
+  type ImageOptimizerFunction,
+} from './src/brevit.js';
+
+// Example 1: Basic usage with default configuration
+async function example1() {
+  const client = new BrevitClient();
+  
+  const data = {
+    user: {
+      name: 'Javian',
+      email: 'support@javianpicardo.com',
+    },
+  };
+
+  const optimized = await client.optimize(data);
+  console.log(optimized);
+  // Output:
+  // user.name: Javian
+  // user.email: support@javianpicardo.com
+}
+
+// Example 2: Custom configuration
+async function example2() {
+  const config: BrevitConfigOptions = {
+    jsonMode: JsonOptimizationMode.Flatten,
+    textMode: TextOptimizationMode.Clean,
+    imageMode: ImageOptimizationMode.Ocr,
+    longTextThreshold: 1000,
+  };
+
+  const client = new BrevitClient(new BrevitConfig(config));
+  
+  const jsonString = '{"order": {"orderId": "o-456", "status": "SHIPPED"}}';
+  const optimized = await client.optimize(jsonString);
+  console.log(optimized);
+}
+
+// Example 3: Custom text optimizer
+async function example3() {
+  const customTextOptimizer: TextOptimizerFunction = async (longText, intent) => {
+    // Call your backend API for summarization
+    const response = await fetch('/api/summarize', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ text: longText, intent }),
+    });
+    
+    const { summary } = await response.json();
+    return summary;
+  };
+
+  const config = new BrevitConfig({
+    textMode: TextOptimizationMode.SummarizeFast,
+  });
+
+  const client = new BrevitClient(config, {
+    textOptimizer: customTextOptimizer,
+  });
+
+  const longText = '...very long text...';
+  const optimized = await client.optimize(longText);
+  console.log(optimized);
+}
+
+// Example 4: Custom image optimizer
+async function example4() {
+  const customImageOptimizer: ImageOptimizerFunction = async (imageData, intent) => {
+    // Convert ArrayBuffer to base64 if needed
+    const base64 = btoa(
+      String.fromCharCode(...new Uint8Array(imageData))
+    );
+
+    // Call your backend OCR API
+    const response = await fetch('/api/ocr', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ image: base64 }),
+    });
+
+    const { text } = await response.json();
+    return text;
+  };
+
+  const config = new BrevitConfig({
+    imageMode: ImageOptimizationMode.Ocr,
+  });
+
+  const client = new BrevitClient(config, {
+    imageOptimizer: customImageOptimizer,
+  });
+
+  const imageData = await fetch('receipt.jpg').then((r) => r.arrayBuffer());
+  const optimized = await client.optimize(imageData);
+  console.log(optimized);
+}
+
+// Example 5: Type-safe usage with interfaces
+interface Order {
+  orderId: string;
+  status: string;
+  items: Array<{
+    sku: string;
+    name: string;
+    quantity: number;
+  }>;
+}
+
+async function example5() {
+  const client = new BrevitClient();
+  
+  const order: Order = {
+    orderId: 'o-456',
+    status: 'SHIPPED',
+    items: [
+      { sku: 'A-88', name: 'Brevit Pro License', quantity: 1 },
+    ],
+  };
+
+  const optimized = await client.optimize(order);
+  console.log(optimized);
+}
+
+// Run examples
+if (import.meta.url === `file://${process.argv[1]}`) {
+  example1().catch(console.error);
+}
+

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "brevit",
+  "version": "0.1.1",
+  "description": "A high-performance JavaScript library for semantically compressing and optimizing data before sending it to a Large Language Model (LLM).",
+  "main": "src/brevit.js",
+  "types": "src/brevit.d.ts",
+  "type": "module",
+  "scripts": {
+    "test": "node test/test.js",
+    "build": "echo 'No build step required for ES modules'"
+  },
+  "keywords": [
+    "llm",
+    "token-optimization",
+    "json-compression",
+    "ai",
+    "semantic-compression"
+  ],
+  "author": {
+    "name": "JavianDev",
+    "email": "support@javianpicardo.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JavianDev/Brevit.js.git"
+  },
+  "optionalDependencies": {
+    "js-yaml": "^4.1.0"
+  }
+}

package/src/brevit.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Brevit.js - TypeScript Definitions
+ * A high-performance JavaScript library for semantically compressing
+ * and optimizing data before sending it to a Large Language Model (LLM).
+ */
+
+/**
+ * JSON optimization modes
+ */
+export const JsonOptimizationMode: {
+  readonly None: 'None';
+  readonly Flatten: 'Flatten';
+  readonly ToYaml: 'ToYaml';
+  readonly Filter: 'Filter';
+};
+
+/**
+ * Text optimization modes
+ */
+export const TextOptimizationMode: {
+  readonly None: 'None';
+  readonly Clean: 'Clean';
+  readonly SummarizeFast: 'SummarizeFast';
+  readonly SummarizeHighQuality: 'SummarizeHighQuality';
+};
+
+/**
+ * Image optimization modes
+ */
+export const ImageOptimizationMode: {
+  readonly None: 'None';
+  readonly Ocr: 'Ocr';
+  readonly Metadata: 'Metadata';
+};
+
+/**
+ * Type for JSON optimization mode values
+ */
+export type JsonOptimizationModeType = typeof JsonOptimizationMode[keyof typeof JsonOptimizationMode];
+
+/**
+ * Type for text optimization mode values
+ */
+export type TextOptimizationModeType = typeof TextOptimizationMode[keyof typeof TextOptimizationMode];
+
+/**
+ * Type for image optimization mode values
+ */
+export type ImageOptimizationModeType = typeof ImageOptimizationMode[keyof typeof ImageOptimizationMode];
+
+/**
+ * Configuration options for BrevitClient
+ */
+export interface BrevitConfigOptions {
+  /**
+   * Strategy for JSON optimization
+   * @default JsonOptimizationMode.Flatten
+   */
+  jsonMode?: JsonOptimizationModeType;
+
+  /**
+   * Strategy for text optimization
+   * @default TextOptimizationMode.Clean
+   */
+  textMode?: TextOptimizationModeType;
+
+  /**
+   * Strategy for image optimization
+   * @default ImageOptimizationMode.Ocr
+   */
+  imageMode?: ImageOptimizationModeType;
+
+  /**
+   * JSON property paths to keep when using Filter mode
+   * @default []
+   */
+  jsonPathsToKeep?: string[];
+
+  /**
+   * Character count threshold to trigger text optimization
+   * @default 500
+   */
+  longTextThreshold?: number;
+}
+
+/**
+ * Configuration object for the BrevitClient
+ */
+export class BrevitConfig {
+  /**
+   * JSON optimization mode
+   */
+  jsonMode: JsonOptimizationModeType;
+
+  /**
+   * Text optimization mode
+   */
+  textMode: TextOptimizationModeType;
+
+  /**
+   * Image optimization mode
+   */
+  imageMode: ImageOptimizationModeType;
+
+  /**
+   * JSON paths to keep for Filter mode
+   */
+  jsonPathsToKeep: string[];
+
+  /**
+   * Long text threshold
+   */
+  longTextThreshold: number;
+
+  /**
+   * Creates a new BrevitConfig instance
+   * @param options Configuration options
+   */
+  constructor(options?: BrevitConfigOptions);
+}
+
+/**
+ * Custom text optimizer function signature
+ * @param longText The text to optimize
+ * @param intent Optional hint about the user's goal
+ * @returns Promise resolving to optimized text
+ */
+export type TextOptimizerFunction = (longText: string, intent?: string | null) => Promise<string>;
+
+/**
+ * Custom image optimizer function signature
+ * @param imageData The image data (ArrayBuffer, Uint8Array, or Buffer)
+ * @param intent Optional hint about the user's goal
+ * @returns Promise resolving to optimized text representation
+ */
+export type ImageOptimizerFunction = (
+  imageData: ArrayBuffer | Uint8Array | Buffer,
+  intent?: string | null
+) => Promise<string>;
+
+/**
+ * Options for BrevitClient constructor
+ */
+export interface BrevitClientOptions {
+  /**
+   * Custom text optimizer function
+   */
+  textOptimizer?: TextOptimizerFunction;
+
+  /**
+   * Custom image optimizer function
+   */
+  imageOptimizer?: ImageOptimizerFunction;
+}
+
+/**
+ * The main client for the Brevit.js library.
+ * This class orchestrates the optimization pipeline.
+ */
+export class BrevitClient {
+  /**
+   * Creates a new BrevitClient instance
+   * @param config Brevit configuration (defaults to new BrevitConfig())
+   * @param options Optional custom optimizers
+   */
+  constructor(config?: BrevitConfig, options?: BrevitClientOptions);
+
+  /**
+   * The primary method. Optimizes any JS object, JSON string,
+   * or data (text, image bytes) into a token-efficient string.
+   *
+   * @param rawData The data to optimize. Can be:
+   *   - A plain JavaScript object
+   *   - A JSON string
+   *   - A text string
+   *   - An ArrayBuffer, Uint8Array, or Buffer (for images)
+   *   - Any other primitive value
+   * @param intent Optional hint about the user's goal, which can
+   *   help the optimizers make better decisions
+   * @returns Promise resolving to an optimized string
+   *
+   * @example
+   * ```typescript
+   * const client = new BrevitClient();
+   * const optimized = await client.optimize({ user: { name: "John" } });
+   * // Returns: "user.name: John"
+   * ```
+   *
+   * @example
+   * ```typescript
+   * const optimized = await client.optimize('{"order": {"id": "123"}}');
+   * // Returns: "order.id: 123"
+   * ```
+   *
+   * @example
+   * ```typescript
+   * const imageData = await fetch('image.jpg').then(r => r.arrayBuffer());
+   * const optimized = await client.optimize(imageData);
+   * // Returns OCR text or metadata
+   * ```
+   */
+  optimize(rawData: unknown, intent?: string | null): Promise<string>;
+}
+
+// Re-export types for convenience
+export type {
+  BrevitConfigOptions,
+  BrevitClientOptions,
+  TextOptimizerFunction,
+  ImageOptimizerFunction,
+};
+