{"_id":"@arkvertex/rayan-lib","_rev":"2-da67894b01b531c98012ca0c3fb532db","name":"@arkvertex/rayan-lib","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@arkvertex/rayan-lib","version":"0.1.0","_id":"@arkvertex/rayan-lib@0.1.0","maintainers":[{"name":"rayanfarhat","email":"rayanfarhat.sh@gmail.com"}],"dist":{"shasum":"df6a95bdbec29e098f164ab0112bc698e325cb1e","tarball":"https://registry.npmjs.org/@arkvertex/rayan-lib/-/rayan-lib-0.1.0.tgz","fileCount":5,"integrity":"sha512-kaVNmW5684HemJfR/8VIWL4xv6lTP8yfhgnw6BEv3neM2AiMunSbs2Ch/VZNa731giIjzURJg4t6ScMvulhYrQ==","signatures":[{"sig":"MEYCIQCpBuYiG/Iv0p8LhwG+N8j44GoMj4YosNU0bpwYkZDwBgIhALfb7zZR/E9Vrb1glxtcaOKRMS/p1wsJgzS41ou93gKD","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":20879},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"9eebb8da20796a349651f3546e49ef888defebaa","private":false,"scripts":{"build":"vite build","publish":"npm publish --access public"},"_npmUser":{"name":"rayanfarhat","email":"rayanfarhat.sh@gmail.com"},"_npmVersion":"11.5.1","description":"A graphics and game engine library","directories":{},"sideEffects":false,"_nodeVersion":"24.4.1","_hasShrinkwrap":false,"devDependencies":{"vite":"^7.2.4","typescript":"~5.9.3","vite-plugin-dts":"^4.5.4"},"_npmOperationalInternal":{"tmp":"tmp/rayan-lib_0.1.0_1765983250538_0.7819058651686481","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@arkvertex/rayan-lib","version":"0.1.1","description":"A graphics and game engine library","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"private":false,"sideEffects":false,"scripts":{"build":"vite build","publish":"npm publish --access public"},"devDependencies":{"typescript":"~5.9.3","vite":"^7.2.4","vite-plugin-dts":"^4.5.4"},"_id":"@arkvertex/rayan-lib@0.1.1","gitHead":"9eebb8da20796a349651f3546e49ef888defebaa","_nodeVersion":"24.4.1","_npmVersion":"11.5.1","dist":{"integrity":"sha512-0XlEnV1tKmHLpT5RX6SWt1sRmLrRY1UDdUy3c+CzjKMM7q8LBOoNrlEE++PD54tE+zKtpG3/q3t42/NkuCE6pw==","shasum":"784d44732b25f97892e30a4bed297e784d03dad8","tarball":"https://registry.npmjs.org/@arkvertex/rayan-lib/-/rayan-lib-0.1.1.tgz","fileCount":5,"unpackedSize":20879,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFhapIsNQSUeNgZluC04UiY70TlQS8jMLiX1Hi/98lZpAiEAmQSn5Xg0RgObLf0hAFQApYAXdaH+wqV3uRBca6zylDY="}]},"_npmUser":{"name":"rayanfarhat","email":"rayanfarhat.sh@gmail.com"},"directories":{},"maintainers":[{"name":"rayanfarhat","email":"rayanfarhat.sh@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/rayan-lib_0.1.1_1765983288446_0.9710046022711396"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-17T14:54:10.417Z","modified":"2025-12-17T14:54:48.788Z","0.1.0":"2025-12-17T14:54:10.669Z","0.1.1":"2025-12-17T14:54:48.590Z"},"description":"A graphics and game engine library","maintainers":[{"name":"rayanfarhat","email":"rayanfarhat.sh@gmail.com"}],"readme":"# Rayan Lib - Frontend Graphics Engine Library\r\n\r\nA minimal, tree-shakeable TypeScript library for frontend graphics and 3D engine development. Optimized for modern bundlers with zero backend dependencies.\r\n\r\n## How the Library Works\r\n\r\n**Rayan Lib** provides modular, tree-shakeable exports organized by functionality:\r\n\r\n```typescript\r\n// Math utilities - Vector, Matrix, Quaternion operations\r\nimport { Vector3, Matrix4, Quaternion } from \"rayan-lib\";\r\n\r\n// Graphics - Camera, Materials, Meshes, Rendering\r\nimport { Camera, Material, Mesh, Renderer, Light } from \"rayan-lib\";\r\n\r\n// Physics - Rigid bodies, colliders, world simulation\r\nimport {\r\n  RigidBody,\r\n  BoxCollider,\r\n  SphereCollider,\r\n  PhysicsWorld,\r\n} from \"rayan-lib\";\r\n```\r\n\r\nEach class is independently importable and only included in your bundle if used.\r\n\r\n## Configuration & Why We Did It This Way\r\n\r\n### 1. **ESM-Only Format** (`index.js`)\r\n\r\n**Configuration:**\r\n\r\n```json\r\n{\r\n  \"type\": \"module\",\r\n  \"main\": \"./dist/index.js\",\r\n  \"exports\": {\r\n    \".\": { \"import\": \"./dist/index.js\" }\r\n  }\r\n}\r\n```\r\n\r\n**Why:**\r\n\r\n- ✅ Enables tree-shaking (removes unused code)\r\n- ✅ Modern, future-proof standard\r\n- ✅ Smaller bundle sizes for consumers\r\n\r\n**What happens without it:**\r\n\r\n- ❌ CommonJS/UMD outputs prevent dead code elimination\r\n- ❌ Bundlers cannot identify unused exports\r\n- ❌ All code shipped to end users, inflating bundle size\r\n\r\n**Example Impact:**\r\n\r\n```typescript\r\n// With ESM + tree-shaking (BEFORE)\r\nimport { Vector3 } from \"rayan-lib\";\r\n// Bundle: ~1.5 KB (only Vector3)\r\n\r\n// With CommonJS (BEFORE)\r\nconst lib = require(\"rayan-lib\");\r\n// Bundle: ~5+ KB (entire library)\r\n```\r\n\r\n### 2. **`\"sideEffects\": false`**\r\n\r\n**Configuration:**\r\n\r\n```json\r\n{\r\n  \"sideEffects\": false\r\n}\r\n```\r\n\r\n**Why:**\r\n\r\n- ✅ Tells bundlers this library has NO side effects on import\r\n- ✅ Allows aggressive tree-shaking\r\n- ✅ Safe to remove unused module exports\r\n\r\n**What happens without it:**\r\n\r\n- ❌ Bundlers assume importing code has side effects\r\n- ❌ Bundlers keep unused modules just in case\r\n- ❌ 30-50% larger final bundles\r\n\r\n**Example:**\r\n\r\n```typescript\r\n// src/math.ts\r\nexport class Vector3 {\r\n  /* ... */\r\n}\r\nexport class Matrix4 {\r\n  /* ... */\r\n}\r\n\r\n// your-app.js\r\nimport { Vector3 } from \"rayan-lib\";\r\n\r\n// WITH sideEffects: false → Matrix4 REMOVED from bundle ✅\r\n// WITHOUT sideEffects: false → Matrix4 KEPT \"just in case\" ❌\r\n```\r\n\r\n### 3. **`moduleResolution: \"bundler\"`**\r\n\r\n**Configuration:**\r\n\r\n```json\r\n{\r\n  \"compilerOptions\": {\r\n    \"moduleResolution\": \"bundler\"\r\n  }\r\n}\r\n```\r\n\r\n**Why:**\r\n\r\n- ✅ Optimized for Vite, Webpack 5+, esbuild\r\n- ✅ Resolves TypeScript files directly\r\n- ✅ Better support for conditional exports\r\n\r\n**What happens without it:**\r\n\r\n- ❌ `\"node\"` resolver follows Node.js conventions\r\n- ❌ Slower resolution, misses optimizations\r\n- ❌ Conditional exports not fully supported\r\n\r\n### 4. **`target: \"ES2020\"` (TypeScript & Vite)**\r\n\r\n**Configuration:**\r\n\r\n```typescript\r\n{\r\n  \"compilerOptions\": { \"target\": \"ES2020\" },\r\n  \"build\": { \"target\": \"ES2020\" }\r\n}\r\n```\r\n\r\n**Why:**\r\n\r\n- ✅ Modern JavaScript features available\r\n- ✅ Smaller output (no transpilation overhead)\r\n- ✅ Matches modern browser support\r\n\r\n**What happens without it:**\r\n\r\n- ❌ ES5 target adds polyfills and transpilation\r\n- ❌ Code bloat (e.g., `class` → verbose `function`)\r\n- ❌ Bundle size increases 20-30%\r\n\r\n**Example:**\r\n\r\n```typescript\r\n// ES2020 output (3 lines)\r\nclass Vector3 {\r\n  constructor(x, y, z) {\r\n    this.x = x;\r\n    this.y = y;\r\n    this.z = z;\r\n  }\r\n}\r\n\r\n// ES5 output (10+ lines with helpers)\r\nvar Vector3 = function () {\r\n  /* complex transpilation */\r\n};\r\n```\r\n\r\n### 5. **`formats: [\"es\"]` (Vite Build)**\r\n\r\n**Configuration:**\r\n\r\n```typescript\r\n{\r\n  build: {\r\n    lib: {\r\n      formats: [\"es\"],\r\n      fileName: () => \"index.js\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n**Why:**\r\n\r\n- ✅ Single, optimized output\r\n- ✅ Bundlers handle the heavy lifting\r\n- ✅ No UMD/CommonJS bloat\r\n\r\n**What happens without it:**\r\n\r\n- ❌ Multiple outputs (ESM + UMD + CommonJS)\r\n- ❌ Larger npm package (3 versions of same code)\r\n- ❌ Users confused which to use\r\n- ❌ npm registry bloat\r\n\r\n### 6. **`vite-plugin-dts`**\r\n\r\n**Configuration:**\r\n\r\n```typescript\r\n{\r\n  plugins: [\r\n    dts({\r\n      include: [\"src\"],\r\n      rollupTypes: true,\r\n    }),\r\n  ];\r\n}\r\n```\r\n\r\n**Why:**\r\n\r\n- ✅ Auto-generates `.d.ts` from TypeScript\r\n- ✅ Bundles all types into single file\r\n- ✅ Consumers get full IntelliSense/autocomplete\r\n\r\n**What happens without it:**\r\n\r\n- ❌ Users have no type definitions\r\n- ❌ No IDE autocomplete\r\n- ❌ TypeScript projects can't use the library properly\r\n- ❌ Community adoption drops\r\n\r\n### 7. **No DOM Types** (`\"lib\": [\"ES2020\"]`)\r\n\r\n**Configuration:**\r\n\r\n```json\r\n{\r\n  \"compilerOptions\": {\r\n    \"lib\": [\"ES2020\"]\r\n  }\r\n}\r\n```\r\n\r\n**Why:**\r\n\r\n- ✅ Library works in Node.js and browsers\r\n- ✅ Pure, environment-agnostic code\r\n- ✅ Graphics module uses only data structures\r\n\r\n**What happens without it:**\r\n\r\n- ❌ Code compiled with DOM types\r\n- ❌ Node.js imports fail (HTMLCanvasElement undefined)\r\n- ❌ Library limited to browser-only\r\n\r\n---\r\n\r\n## Bundle Size Comparison\r\n\r\n| Config                     | Bundle Size  | Tree-Shaking  | Notes                |\r\n| -------------------------- | ------------ | ------------- | -------------------- |\r\n| ✅ Our Config              | 1.63 KB gzip | ✅ Aggressive | Optimized            |\r\n| CommonJS only              | 5+ KB gzip   | ❌ None       | Cannot tree-shake    |\r\n| With `\"sideEffects\": true` | 3+ KB gzip   | ⚠️ Partial    | Keeps unused modules |\r\n| UMD/IIFE format            | 7+ KB gzip   | ❌ None       | Not modular          |\r\n\r\n---\r\n\r\n## Installation & Usage\r\n\r\n```bash\r\nnpm install rayan-lib\r\n```\r\n\r\n```typescript\r\nimport { Vector3, Camera, Renderer, RigidBody } from \"rayan-lib\";\r\n\r\n// Only used exports are bundled\r\nconst v = new Vector3(1, 2, 3);\r\nconst camera = new Camera();\r\nconst renderer = new Renderer(\"webgl\", 1024, 768);\r\nconst body = new RigidBody();\r\n```\r\n\r\n---\r\n\r\n## Understanding Tree-Shaking with Dependencies\r\n\r\n**Question:** If `Matrix4` uses `Vector3`, will tree-shaking remove `Vector3` and cause runtime errors?\r\n\r\n**Answer:** ✅ **No runtime errors** - Tree-shakers are smart about dependencies.\r\n\r\n### Example: Matrix4 uses Vector3\r\n\r\n```typescript\r\n// math.ts\r\nexport class Vector3 {\r\n  /* ... */\r\n}\r\n\r\nexport class Matrix4 {\r\n  translate(v: Vector3): this {\r\n    // ← Depends on Vector3\r\n    this.data[12] += v.x;\r\n    return this;\r\n  }\r\n}\r\n```\r\n\r\n### Scenario 1: Using Matrix4 with translate()\r\n\r\n```typescript\r\nimport { Matrix4, Vector3 } from \"rayan-lib\";\r\n\r\nconst m = new Matrix4();\r\nconst v = new Vector3(1, 2, 3);\r\nm.translate(v); // ← This USES the translate() method\r\n```\r\n\r\n**What tree-shaker does:**\r\n\r\n1. Sees `translate()` method is used\r\n2. Analyzes `translate()` → depends on Vector3\r\n3. **Keeps both** Matrix4 and Vector3 ✅\r\n\r\n**Bundle includes:** Matrix4 + Vector3 + code using both\r\n\r\n### Scenario 2: Using Matrix4 without translate()\r\n\r\n```typescript\r\nimport { Matrix4 } from \"rayan-lib\";\r\n\r\nconst m = new Matrix4();\r\nm.identity(); // ← Only identity() method used\r\n```\r\n\r\n**What tree-shaker does:**\r\n\r\n1. Sees `identity()` method used\r\n2. Analyzes `identity()` → NO Vector3 dependency\r\n3. Sees `translate()` and `scale()` methods not used\r\n4. **Removes unused methods** + Vector3 ✅\r\n\r\n**Bundle includes:** Only Matrix4.identity()\r\n\r\n### The Smart Part\r\n\r\nTree-shakers don't just look at imports—they analyze **actual usage**:\r\n\r\n```typescript\r\n// ❌ Imported but not used → REMOVED\r\nimport { Vector3 } from \"rayan-lib\";\r\n\r\n// ✅ Used in code → KEPT\r\nimport { Matrix4 } from \"rayan-lib\";\r\nconst m = new Matrix4();\r\n```\r\n\r\n### Dependency Analysis\r\n\r\n```\r\nYour Code\r\n  ↓\r\nUses Matrix4.translate()\r\n  ↓\r\nMatrix4.translate() needs Vector3\r\n  ↓\r\nVector3 included automatically ✅\r\n```\r\n\r\n**Summary:**\r\n\r\n- Tree-shaking is **dependency-aware**\r\n- Unused dependencies are removed\r\n- **Used** dependencies are automatically kept\r\n- **No runtime errors** occur\r\n- Zero manual dependency management needed\r\n\r\n---\r\n\r\n## Architecture\r\n\r\n```\r\nsrc/\r\n├── math.ts         → Vector3, Matrix4, Quaternion\r\n├── graphics.ts     → Camera, Material, Mesh, Renderer, Light\r\n├── physics.ts      → RigidBody, Colliders, PhysicsWorld\r\n└── index.ts        → Central export point\r\n```\r\n\r\nAll modules export named exports for tree-shaking.\r\n\r\n---\r\n\r\n## Key Takeaways\r\n\r\n| Decision             | Benefit            | Alternative Cost                 |\r\n| -------------------- | ------------------ | -------------------------------- |\r\n| ESM only             | Tree-shaking       | +30-50% bundle size              |\r\n| `sideEffects: false` | Dead code removal  | Bundler includes unused code     |\r\n| `bundler` resolution | Optimized          | Slower, misses optimizations     |\r\n| ES2020 target        | Modern, small      | +20-30% with ES5 transpilation   |\r\n| Single format        | Clean              | Multiple output files, confusion |\r\n| DTS generation       | TypeScript support | No IDE support for consumers     |\r\n| No DOM types         | Universal          | Node.js incompatible             |\r\n\r\n---\r\n\r\n**Bottom Line:** Every configuration choice is optimized for minimal bundle size while maintaining full TypeScript support and tree-shaking capability. Removing any setting increases overhead for end users.\r\n","readmeFilename":"README.md"}