@reliverse/relico 1.3.1 → 1.3.2

package/.cursor/rules/general-rules.mdc

@@ -1,276 +0,0 @@
----
-globs: *.ts
-alwaysApply: false
----
-
-
-# Dependency-Free TypeScript Library: General Rules
-
-Always follow ultracite's coding rules. Ultracite enforces strict type safety, accessibility standards, and consistent code quality for JavaScript/TypeScript projects using Biome's lightning-fast formatter and linter.
-
-## Key Principles
-
-- Zero configuration required
-- Subsecond performance
-- Maximum type safety
-
-## Remember
-
-1. Consider edge cases and error scenarios
-2. Follow the rules below strictly
-3. As an AI you can't see terminal's colors
-
-## Rules
-
-### Code Complexity and Quality
-
-- Don't use consecutive spaces in regular expression literals.
-- Don't use the `arguments` object.
-- Don't use primitive type aliases or misleading types.
-- Don't use the comma operator.
-- Don't use empty type parameters in type aliases and interfaces.
-- Don't write functions that exceed a given Cognitive Complexity score.
-- Don't nest describe() blocks too deeply in test files.
-- Don't use unnecessary boolean casts.
-- Don't use unnecessary callbacks with flatMap.
-- Use for...of statements instead of Array.forEach.
-- Don't create classes that only have static members (like a static namespace).
-- Don't use this and super in static contexts.
-- Don't use unnecessary catch clauses.
-- Don't use unnecessary constructors.
-- Don't use unnecessary continue statements.
-- Don't export empty modules that don't change anything.
-- Don't use unnecessary escape sequences in regular expression literals.
-- Don't use unnecessary fragments.
-- Don't use unnecessary labels.
-- Don't use unnecessary nested block statements.
-- Don't rename imports, exports, and destructured assignments to the same name.
-- Don't use unnecessary string or template literal concatenation.
-- Don't use String.raw in template literals when there are no escape sequences.
-- Don't use useless case statements in switch statements.
-- Don't use ternary operators when simpler alternatives exist.
-- Don't use useless `this` aliasing.
-- Don't use any or unknown as type constraints.
-- Don't initialize variables to undefined.
-- Don't use the void operators (they're not familiar).
-- Use arrow functions instead of function expressions.
-- Use Date.now() to get milliseconds since the Unix Epoch.
-- Use .flatMap() instead of map().flat() when possible.
-- Use literal property access instead of computed property access.
-- Don't use parseInt() or Number.parseInt() when binary, octal, or hexadecimal literals work.
-- Use concise optional chaining instead of chained logical expressions.
-- Use regular expression literals instead of the RegExp constructor when possible.
-- Don't use number literal object member names that aren't base 10 or use underscore separators.
-- Remove redundant terms from logical expressions.
-- Use while loops instead of for loops when you don't need initializer and update expressions.
-- Don't pass children as props.
-- Don't reassign const variables.
-- Don't use constant expressions in conditions.
-- Don't use `Math.min` and `Math.max` to clamp values when the result is constant.
-- Don't return a value from a constructor.
-- Don't use empty character classes in regular expression literals.
-- Don't use empty destructuring patterns.
-- Don't call global object properties as functions.
-- Don't declare functions and vars that are accessible outside their block.
-- Make sure builtins are correctly instantiated.
-- Don't use super() incorrectly inside classes. Also check that super() is called in classes that extend other constructors.
-- Don't use variables and function parameters before they're declared.
-- Don't use 8 and 9 escape sequences in string literals.
-- Don't use literal numbers that lose precision.
-
-### Correctness and Safety
-
-- Don't assign a value to itself.
-- Don't return a value from a setter.
-- Don't compare expressions that modify string case with non-compliant values.
-- Don't use lexical declarations in switch clauses.
-- Don't use variables that haven't been declared in the document.
-- Don't write unreachable code.
-- Make sure super() is called exactly once on every code path in a class constructor before this is accessed if the class has a superclass.
-- Don't use control flow statements in finally blocks.
-- Don't use optional chaining where undefined values aren't allowed.
-- Don't have unused function parameters.
-- Don't have unused imports.
-- Don't have unused labels.
-- Don't have unused private class members.
-- Don't have unused variables.
-- Make sure void (self-closing) elements don't have children.
-- Don't return a value from a function with the return type 'void'
-- Use isNaN() when checking for NaN.
-- Make sure "for" loop update clauses move the counter in the right direction.
-- Make sure typeof expressions are compared to valid values.
-- Make sure generator functions contain yield.
-- Don't use await inside loops.
-- Don't use bitwise operators.
-- Don't use expressions where the operation doesn't change the value.
-- Make sure Promise-like statements are handled appropriately.
-- Don't use __dirname and__filename in the global scope.
-- Prevent import cycles.
-- Don't use configured elements.
-- Don't hardcode sensitive data like API keys and tokens.
-- Don't let variable declarations shadow variables from outer scopes.
-- Don't use the TypeScript directive @ts-ignore.
-- Prevent duplicate polyfills from Polyfill.io.
-- Don't use useless backreferences in regular expressions that always match empty strings.
-- Don't use unnecessary escapes in string literals.
-- Don't use useless undefined.
-- Make sure getters and setters for the same property are next to each other in class and object definitions.
-- Make sure object literals are declared consistently (defaults to explicit definitions).
-- Use static Response methods instead of new Response() constructor when possible.
-- Make sure switch-case statements are exhaustive.
-- Make sure the `preconnect` attribute is used when using Google Fonts.
-- Use `Array#{indexOf,lastIndexOf}()` instead of `Array#{findIndex,findLastIndex}()` when looking for the index of an item.
-- Make sure iterable callbacks return consistent values.
-- Use `with { type: "json" }` for JSON module imports.
-- Use numeric separators in numeric literals.
-- Use object spread instead of `Object.assign()` when constructing new objects.
-- Always use the radix argument when using `parseInt()`.
-- Make sure JSDoc comment lines start with a single asterisk, except for the first one.
-- Include a description parameter for `Symbol()`.
-- Don't use spread (`...`) syntax on accumulators.
-- Don't use the `delete` operator.
-- Don't access namespace imports dynamically.
-- Don't use namespace imports.
-- Declare regex literals at the top level.
-- Don't use `target="_blank"` without `rel="noopener"`.
-
-### TypeScript Best Practices
-
-- Don't use TypeScript enums.
-- Don't export imported variables.
-- Don't add type annotations to variables, parameters, and class properties that are initialized with literal expressions.
-- Don't use TypeScript namespaces.
-- Don't use non-null assertions with the `!` postfix operator.
-- Don't use parameter properties in class constructors.
-- Don't use user-defined types.
-- Use `as const` instead of literal types and type annotations.
-- Use either `T[]` or `Array<T>` consistently.
-- Initialize each enum member value explicitly.
-- Use `export type` for types.
-- Use `import type` for types.
-- Make sure all enum members are literal values.
-- Don't use TypeScript const enum.
-- Don't declare empty interfaces.
-- Don't let variables evolve into any type through reassignments.
-- Don't use the any type.
-- Don't misuse the non-null assertion operator (!) in TypeScript files.
-- Don't use implicit any type on variable declarations.
-- Don't merge interfaces and classes unsafely.
-- Don't use overload signatures that aren't next to each other.
-- Use the namespace keyword instead of the module keyword to declare TypeScript namespaces.
-
-### Style and Consistency
-
-- Don't use global `eval()`.
-- Don't use callbacks in asynchronous tests and hooks.
-- Don't use negation in `if` statements that have `else` clauses.
-- Don't use nested ternary expressions.
-- Don't reassign function parameters.
-- This rule lets you specify global variable names you don't want to use in your application.
-- Don't use specified modules when loaded by import or require.
-- Don't use constants whose value is the upper-case version of their name.
-- Use `String.slice()` instead of `String.substr()` and `String.substring()`.
-- Don't use template literals if you don't need interpolation or special-character handling.
-- Don't use `else` blocks when the `if` block breaks early.
-- Don't use yoda expressions.
-- Don't use Array constructors.
-- Use `at()` instead of integer index access.
-- Follow curly brace conventions.
-- Use `else if` instead of nested `if` statements in `else` clauses.
-- Use single `if` statements instead of nested `if` clauses.
-- Use `new` for all builtins except `String`, `Number`, and `Boolean`.
-- Use consistent accessibility modifiers on class properties and methods.
-- Use `const` declarations for variables that are only assigned once.
-- Put default function parameters and optional function parameters last.
-- Include a `default` clause in switch statements.
-- Use the `**` operator instead of `Math.pow`.
-- Use `for-of` loops when you need the index to extract an item from the iterated array.
-- Use `node:assert/strict` over `node:assert`.
-- Use the `node:` protocol for Node.js builtin modules.
-- Use Number properties instead of global ones.
-- Use assignment operator shorthand where possible.
-- Use function types instead of object types with call signatures.
-- Use template literals over string concatenation.
-- Use `new` when throwing an error.
-- Don't throw non-Error values.
-- Use `String.trimStart()` and `String.trimEnd()` over `String.trimLeft()` and `String.trimRight()`.
-- Use standard constants instead of approximated literals.
-- Don't assign values in expressions.
-- Don't use async functions as Promise executors.
-- Don't reassign exceptions in catch clauses.
-- Don't reassign class members.
-- Don't compare against -0.
-- Don't use labeled statements that aren't loops.
-- Don't use void type outside of generic or return types.
-- Don't use console.
-- Don't use control characters and escape sequences that match control characters in regular expression literals.
-- Don't use debugger.
-- Don't assign directly to document.cookie.
-- Use `===` and `!==`.
-- Don't use duplicate case labels.
-- Don't use duplicate class members.
-- Don't use duplicate conditions in if-else-if chains.
-- Don't use two keys with the same name inside objects.
-- Don't use duplicate function parameter names.
-- Don't have duplicate hooks in describe blocks.
-- Don't use empty block statements and static blocks.
-- Don't let switch clauses fall through.
-- Don't reassign function declarations.
-- Don't allow assignments to native objects and read-only global variables.
-- Use Number.isFinite instead of global isFinite.
-- Use Number.isNaN instead of global isNaN.
-- Don't assign to imported bindings.
-- Don't use irregular whitespace characters.
-- Don't use labels that share a name with a variable.
-- Don't use characters made with multiple code points in character class syntax.
-- Make sure to use new and constructor properly.
-- Don't use shorthand assign when the variable appears on both sides.
-- Don't use octal escape sequences in string literals.
-- Don't use Object.prototype builtins directly.
-- Don't redeclare variables, functions, classes, and types in the same scope.
-- Don't have redundant "use strict".
-- Don't compare things where both sides are exactly the same.
-- Don't let identifiers shadow restricted names.
-- Don't use sparse arrays (arrays with holes).
-- Don't use template literal placeholder syntax in regular strings.
-- Don't use the then property.
-- Don't use unsafe negation.
-- Don't use var.
-- Don't use with statements in non-strict contexts.
-- Make sure async functions actually use await.
-- Make sure default clauses in switch statements come last.
-- Make sure to pass a message value when creating a built-in error.
-- Make sure get methods always return a value.
-- Use a recommended display strategy with Google Fonts.
-- Make sure for-in loops include an if statement.
-- Use Array.isArray() instead of instanceof Array.
-- Make sure to use the digits argument with Number#toFixed().
-- Make sure to use the "use strict" directive in script files.
-
-### Testing Best Practices
-
-- Don't use export or module.exports in test files.
-- Don't use focused tests.
-- Make sure the assertion function, like expect, is placed inside an it() function call.
-- Don't use disabled tests.
-- Use Bun.
-
-## Example: Error Handling
-
-```typescript
-// ✅ Good: Comprehensive error handling
-try {
-  const result = await fetchData();
-  return { success: true, data: result };
-} catch (error) {
-  console.error('API call failed:', error);
-  return { success: false, error: error.message };
-}
-
-// ❌ Bad: Swallowing errors
-try {
-  return await fetchData();
-} catch (e) {
-  console.log(e);
-}
-```

package/.vscode/extensions.json

@@ -1,8 +0,0 @@
-{
-  "recommendations": [
-    "fabiospampinato.vscode-open-multiple-files",
-    "davidanson.vscode-markdownlint",
-    "usernamehw.errorlens",
-    "yoavbls.pretty-ts-errors"
-  ]
-}

package/.vscode/settings.json

@@ -1,45 +0,0 @@
-{
-  "editor.formatOnSave": true,
-  "editor.codeActionsOnSave": {
-    "source.addMissingImports.ts": "never",
-    "source.biome": "explicit",
-    "source.fixAll.biome": "explicit",
-    "source.fixAll.ts": "never",
-    "source.organizeImports.biome": "explicit",
-    "source.organizeImports": "never",
-    "source.removeUnused.ts": "never",
-    "source.removeUnusedImports": "never",
-    "source.sortImports": "never"
-  },
-  "editor.defaultFormatter": "biomejs.biome",
-  "[typescript]": {
-    "editor.defaultFormatter": "biomejs.biome"
-  },
-  "[json]": {
-    "editor.defaultFormatter": "biomejs.biome"
-  },
-  "[javascript]": {
-    "editor.defaultFormatter": "biomejs.biome"
-  },
-  "[jsonc]": {
-    "editor.defaultFormatter": "biomejs.biome"
-  },
-  "[typescriptreact]": {
-    "editor.defaultFormatter": "biomejs.biome"
-  },
-  "[markdown]": {
-    "editor.defaultFormatter": "DavidAnson.vscode-markdownlint"
-  },
-  "markdownlint.config": {
-    "MD033": false,
-    "MD024": false
-  },
-  "json.schemaDownload.enable": true,
-  "css.lint.unknownAtRules": "ignore",
-  "emmet.showExpandedAbbreviation": "never",
-  "typescript.preferences.importModuleSpecifier": "shortest",
-  "typescript.updateImportsOnFileMove.enabled": "never",
-  "javascript.updateImportsOnFileMove.enabled": "never",
-  "typescript.updateImportsOnPaste.enabled": false,
-  "javascript.updateImportsOnPaste.enabled": false
-}

package/biome.json

@@ -1,78 +0,0 @@
-{
-  "$schema": "https://biomejs.dev/schemas/2.2.0/schema.json",
-  "extends": ["ultracite"],
-  "vcs": {
-    "enabled": false,
-    "clientKind": "git",
-    "useIgnoreFile": false
-  },
-  "files": {
-    "ignoreUnknown": false,
-    "maxSize": 1700000,
-    "includes": [
-      "**",
-      "!**/.js",
-      "!**/.d.ts",
-      "!**/_generated",
-      "!**/.basehub",
-      "!**/.expo",
-      "!**/.next",
-      "!**/.nuxt",
-      "!**/.react-email",
-      "!**/.source",
-      "!**/.turbo",
-      "!**/.vercel",
-      "!**/.wrangler",
-      "!**/.zed",
-      "!**/dev-dist",
-      "!**/dist-*",
-      "!**/dist",
-      "!**/drizzle/migrations",
-      "!**/node_modules",
-      "!**/routeTree.gen.ts",
-      "!**/src-tauri"
-    ]
-  },
-  "formatter": {
-    "enabled": true,
-    "indentStyle": "space",
-    "lineWidth": 100
-  },
-  "linter": {
-    "enabled": true,
-    "rules": {
-      "recommended": true,
-      "suspicious": { "noConsole": "off" },
-      "style": { "useNodejsImportProtocol": "off", "noMagicNumbers": "off" },
-      "complexity": { "noExcessiveLinesPerFunction": "off" },
-      "nursery": {
-        "useConsistentTypeDefinitions": {
-          "level": "error",
-          "options": { "style": "interface" }
-        }
-      }
-    }
-  },
-  "javascript": {
-    "globals": ["Bun"],
-    "formatter": {
-      "jsxQuoteStyle": "double",
-      "quoteProperties": "asNeeded",
-      "trailingCommas": "all",
-      "semicolons": "always",
-      "arrowParentheses": "always",
-      "bracketSpacing": true,
-      "bracketSameLine": false,
-      "quoteStyle": "double",
-      "attributePosition": "auto"
-    }
-  },
-  "assist": {
-    "enabled": true,
-    "actions": {
-      "source": {
-        "organizeImports": "on"
-      }
-    }
-  }
-}

package/examples/benchmarks/bundle-size.ts

@@ -1,143 +0,0 @@
-// Bundle size analysis for relico
-import { readFileSync, statSync } from "fs";
-import { dirname, resolve } from "path";
-import { fileURLToPath } from "url";
-import { config, getEnabledDirs, getFilePaths, getImportPath } from "./config";
-
-// Get the directory where this benchmark file is located
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// Constants for size formatting
-const BYTES_PER_KB = 1024;
-const BYTES_PER_MB = 1024 * 1024;
-const NEWLINE_LENGTH = 1;
-const PERCENT_MULTIPLIER = 100;
-const DECIMAL_PLACES = 1;
-const SEPARATOR_LENGTH = 60;
-
-function getFileSize(path: string): number {
-  try {
-    const stats = statSync(path);
-    return stats.size;
-  } catch {
-    return 0;
-  }
-}
-
-function formatSize(bytes: number): string {
-  if (bytes < BYTES_PER_KB) {
-    return `${bytes}B`;
-  }
-  if (bytes < BYTES_PER_MB) {
-    return `${(bytes / BYTES_PER_KB).toFixed(DECIMAL_PLACES)}KB`;
-  }
-  return `${(bytes / BYTES_PER_MB).toFixed(DECIMAL_PLACES)}MB`;
-}
-
-function analyzeFile(filePath: string): { types: number; constants: number; logic: number } {
-  try {
-    const sourceCode = readFileSync(filePath, "utf8");
-    const lines = sourceCode.split("\n");
-
-    let typeDefinitions = 0;
-    let constants = 0;
-    let logic = 0;
-
-    for (const line of lines) {
-      const trimmed = line.trim();
-
-      // Type definitions
-      if (trimmed.includes("type ") || trimmed.includes("interface ")) {
-        typeDefinitions += line.length + NEWLINE_LENGTH;
-        continue;
-      }
-
-      // Constants and color data
-      if (
-        trimmed.includes("const ") ||
-        trimmed.includes("COLOR_LEVEL") ||
-        trimmed.includes("SGR_")
-      ) {
-        constants += line.length + NEWLINE_LENGTH;
-        continue;
-      }
-
-      // Everything else is logic
-      if (trimmed.length > 0) {
-        logic += line.length + NEWLINE_LENGTH;
-      }
-    }
-
-    return { types: typeDefinitions, constants, logic };
-  } catch (error) {
-    console.warn(`⚠️  Could not analyze ${filePath}:`, error);
-    return { types: 0, constants: 0, logic: 0 };
-  }
-}
-
-function analyzeSingleDirectory(dir: "src" | "distNpmBin"): void {
-  const importPath = getImportPath(dir);
-  const filePaths = getFilePaths(dir);
-
-  console.log(`\n🔍 Analyzing ${dir.toUpperCase()} directory: ${importPath}`);
-  console.log("=".repeat(SEPARATOR_LENGTH));
-
-  // Analyze JavaScript/TypeScript file
-  if (filePaths.js) {
-    const jsFilePath = resolve(__dirname, filePaths.js);
-    console.log(`📄 JavaScript/TypeScript file: ${filePaths.js}`);
-    console.log(`Resolved path: ${jsFilePath}`);
-
-    const jsFileSize = getFileSize(jsFilePath);
-    if (jsFileSize === 0) {
-      console.log(`❌ File not found or empty: ${jsFilePath}`);
-    } else {
-      console.log(`File size: ${formatSize(jsFileSize)}`);
-
-      const jsAnalysis = analyzeFile(jsFilePath);
-
-      console.log("\nBreakdown:");
-      console.log(
-        `- Types: ${formatSize(jsAnalysis.types)} (${((jsAnalysis.types / jsFileSize) * PERCENT_MULTIPLIER).toFixed(DECIMAL_PLACES)}%)`,
-      );
-      console.log(
-        `- Constants: ${formatSize(jsAnalysis.constants)} (${((jsAnalysis.constants / jsFileSize) * PERCENT_MULTIPLIER).toFixed(DECIMAL_PLACES)}%)`,
-      );
-      console.log(
-        `- Logic: ${formatSize(jsAnalysis.logic)} (${((jsAnalysis.logic / jsFileSize) * PERCENT_MULTIPLIER).toFixed(DECIMAL_PLACES)}%)`,
-      );
-
-      if (config.bundleAnalysis.analyzeDependencies) {
-        console.log("\n📊 Additional Info:");
-        try {
-          const sourceCode = readFileSync(jsFilePath, "utf8");
-          const lines = sourceCode.split("\n");
-          console.log(`- Total lines: ${lines.length}`);
-          console.log("- File type: TypeScript");
-        } catch (error) {
-          console.log(`- Could not read file for line count: ${error}`);
-        }
-      }
-    }
-  }
-}
-
-function analyzeAllDirectories(): void {
-  const enabledDirs = getEnabledDirs();
-
-  for (const dir of enabledDirs) {
-    analyzeSingleDirectory(dir);
-  }
-}
-
-// Main execution
-console.log("📦 Relico Bundle Size Analysis");
-console.log("=".repeat(50));
-
-console.log("Starting analysis...");
-analyzeAllDirectories();
-console.log("\n✅ All analyses completed!");
-console.log("Starting analysis...");
-analyzeAllDirectories();
-console.log("\n✅ All analyses completed!");

package/examples/benchmarks/config.example.ts

@@ -1,55 +0,0 @@
-// Example configuration for relico benchmarks
-// Copy this file to config.ts and modify as needed
-
-import type { BenchmarkConfig } from "./config";
-
-// Custom configuration example
-export const customConfig: BenchmarkConfig = {
-  sourceDirs: {
-    src: "../../src", // Source TypeScript files
-    distNpmBin: "../../dist-npm/bin", // Binary distribution files
-  },
-
-  // Choose which directories to test
-  enabledDirs: ["src", "distNpmBin"], // Only test src and dist-npm/bin
-
-  performance: {
-    iterations: 50_000, // Reduce iterations for faster testing
-    warmupRuns: 500, // Reduce warmup runs
-  },
-
-  bundleAnalysis: {
-    includeSourceMaps: false, // Skip source map analysis
-    analyzeDependencies: true, // Include dependency analysis
-  },
-};
-
-// Example: Test only source files
-export const sourceOnlyConfig: BenchmarkConfig = {
-  ...customConfig,
-  enabledDirs: ["src"],
-};
-
-// Example: Test only built files
-export const builtOnlyConfig: BenchmarkConfig = {
-  ...customConfig,
-  enabledDirs: ["distNpmBin"],
-};
-
-// Example: High-performance testing
-export const highPerfConfig: BenchmarkConfig = {
-  ...customConfig,
-  performance: {
-    iterations: 1_000_000, // 1M iterations for accurate results
-    warmupRuns: 10_000, // 10K warmup runs
-  },
-};
-
-// Example: Quick testing
-export const quickConfig: BenchmarkConfig = {
-  ...customConfig,
-  performance: {
-    iterations: 10_000, // 10K iterations for quick results
-    warmupRuns: 100, // Minimal warmup
-  },
-};