@geenius/tools 0.1.0

package/packages/devtools/src/index.ts

@@ -0,0 +1,377 @@
+/**
+ * @geenius-tools/devtools — Development tools and utilities
+ *
+ * Provides utilities for development, debugging, and development-time configuration.
+ * Includes feature flags, mock data, and debugging helpers.
+ */
+
+/**
+ * Feature flag configuration
+ */
+export interface FeatureFlag {
+  /** Flag name */
+  name: string
+  /** Whether flag is enabled */
+  enabled: boolean
+  /** When flag was created */
+  createdAt?: Date
+  /** When flag will be removed */
+  expiresAt?: Date
+  /** Optional description */
+  description?: string
+}
+
+/**
+ * Feature flags manager
+ *
+ * @example
+ * ```ts
+ * const flags = new FeatureFlagManager()
+ * flags.set('newUI', true)
+ * if (flags.isEnabled('newUI')) {
+ *   // Use new UI
+ * }
+ * ```
+ */
+export class FeatureFlagManager {
+  private flags: Map<string, FeatureFlag> = new Map()
+  private listeners: Set<(flag: string, enabled: boolean) => void> = new Set()
+
+  /**
+   * Sets a feature flag
+   */
+  set(name: string, enabled: boolean, description?: string) {
+    this.flags.set(name, {
+      name,
+      enabled,
+      description,
+      createdAt: new Date(),
+    })
+
+    // Notify listeners
+    for (const listener of this.listeners) {
+      listener(name, enabled)
+    }
+  }
+
+  /**
+   * Checks if feature is enabled
+   */
+  isEnabled(name: string): boolean {
+    return this.flags.get(name)?.enabled ?? false
+  }
+
+  /**
+   * Gets flag info
+   */
+  getFlag(name: string): FeatureFlag | undefined {
+    return this.flags.get(name)
+  }
+
+  /**
+   * Gets all flags
+   */
+  getAllFlags(): FeatureFlag[] {
+    return Array.from(this.flags.values())
+  }
+
+  /**
+   * Removes a flag
+   */
+  remove(name: string) {
+    this.flags.delete(name)
+  }
+
+  /**
+   * Clears all flags
+   */
+  clear() {
+    this.flags.clear()
+  }
+
+  /**
+   * Listens for flag changes
+   */
+  onChange(callback: (name: string, enabled: boolean) => void): () => void {
+    this.listeners.add(callback)
+    return () => this.listeners.delete(callback)
+  }
+}
+
+/**
+ * Type-safe feature flag helper
+ *
+ * @example
+ * ```ts
+ * type AppFlags = 'newUI' | 'betaFeatures' | 'darkMode'
+ * const flags = createTypedFlags<AppFlags>()
+ * flags.set('newUI', true)
+ * ```
+ */
+export function createTypedFlags<T extends string = string>() {
+  const manager = new FeatureFlagManager()
+
+  return {
+    set: (name: T, enabled: boolean) => manager.set(name, enabled),
+    isEnabled: (name: T) => manager.isEnabled(name),
+    getFlag: (name: T) => manager.getFlag(name),
+    getAllFlags: () => manager.getAllFlags(),
+    remove: (name: T) => manager.remove(name),
+    clear: () => manager.clear(),
+    onChange: (callback: (name: T, enabled: boolean) => void) =>
+      manager.onChange(callback as any),
+  }
+}
+
+/**
+ * Development mode detector
+ *
+ * @returns True if running in development
+ */
+export function isDevelopment(): boolean {
+  if (typeof process !== 'undefined' && process.env) {
+    return (
+      process.env.NODE_ENV === 'development' ||
+      process.env.DEBUG === 'true' ||
+      false
+    )
+  }
+
+  if (typeof window !== 'undefined') {
+    return (
+      window.location.hostname === 'localhost' ||
+      window.location.hostname === '127.0.0.1'
+    )
+  }
+
+  return false
+}
+
+/**
+ * Production mode detector
+ *
+ * @returns True if running in production
+ */
+export function isProduction(): boolean {
+  if (typeof process !== 'undefined' && process.env) {
+    return process.env.NODE_ENV === 'production'
+  }
+
+  return !isDevelopment()
+}
+
+/**
+ * Debug helper for logging in dev mode only
+ *
+ * @example
+ * ```ts
+ * devLog('user state:', user)
+ * ```
+ */
+export function devLog(...args: any[]) {
+  if (isDevelopment()) {
+    console.log('[DEV]', ...args)
+  }
+}
+
+/**
+ * Debug warning in dev mode only
+ */
+export function devWarn(...args: any[]) {
+  if (isDevelopment()) {
+    console.warn('[DEV WARN]', ...args)
+  }
+}
+
+/**
+ * Assertion utility for development
+ *
+ * @throws Error if condition is false in development
+ */
+export function devAssert(condition: boolean, message: string) {
+  if (isDevelopment() && !condition) {
+    throw new Error(`[DEV ASSERTION] ${message}`)
+  }
+}
+
+/**
+ * Creates a mock data generator
+ *
+ * @example
+ * ```ts
+ * const mockUsers = generateMocks(10, () => ({
+ *   id: faker.string.uuid(),
+ *   name: faker.person.fullName(),
+ *   email: faker.internet.email()
+ * }))
+ * ```
+ */
+export function generateMocks<T>(count: number, generator: () => T): T[] {
+  return Array.from({ length: count }, () => generator())
+}
+
+/**
+ * Measures React component render time
+ *
+ * @example
+ * ```ts
+ * function MyComponent() {
+ *   devMeasureRender('MyComponent')
+ *   return <div>...</div>
+ * }
+ * ```
+ */
+export function devMeasureRender(componentName: string) {
+  if (!isDevelopment()) return
+
+  const start = performance.now()
+
+  return () => {
+    const duration = performance.now() - start
+    if (duration > 16) {
+      // Longer than 60fps frame
+      console.warn(
+        `[PERF] ${componentName} render took ${duration.toFixed(2)}ms`
+      )
+    }
+  }
+}
+
+/**
+ * Deep object comparison for development assertions
+ *
+ * @returns True if objects are deeply equal
+ */
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true
+
+  if (
+    typeof a !== 'object' ||
+    typeof b !== 'object' ||
+    a === null ||
+    b === null
+  ) {
+    return false
+  }
+
+  const keysA = Object.keys(a)
+  const keysB = Object.keys(b)
+
+  if (keysA.length !== keysB.length) return false
+
+  for (const key of keysA) {
+    if (!deepEqual((a as any)[key], (b as any)[key])) {
+      return false
+    }
+  }
+
+  return true
+}
+
+/**
+ * Creates a performance monitor that logs slow operations
+ *
+ * @example
+ * ```ts
+ * const monitor = createSlowOpMonitor(100) // log if > 100ms
+ * await monitor.track('api-call', async () => {
+ *   return fetch('/api/data')
+ * })
+ * ```
+ */
+export function createSlowOpMonitor(thresholdMs: number) {
+  return {
+    track: async <T,>(name: string, fn: () => Promise<T>): Promise<T> => {
+      const start = performance.now()
+      const result = await fn()
+      const duration = performance.now() - start
+
+      if (duration > thresholdMs) {
+        console.warn(
+          `[SLOW OP] ${name} took ${duration.toFixed(2)}ms (threshold: ${thresholdMs}ms)`
+        )
+      }
+
+      return result
+    },
+  }
+}
+
+/**
+ * Type assertion helper
+ *
+ * @throws Error if value is undefined/null in development
+ *
+ * @example
+ * ```ts
+ * const user = devAssertExists(data.user, 'user')
+ * ```
+ */
+export function devAssertExists<T>(value: T | null | undefined, name: string): T {
+  if (isDevelopment() && (value === null || value === undefined)) {
+    throw new Error(`Expected ${name} to exist, got ${value}`)
+  }
+  return value as T
+}
+
+/**
+ * Global devtools window object
+ */
+export interface DevtoolsWindow {
+  __GEENIUS_DEVTOOLS__?: {
+    flags: FeatureFlagManager
+    isDevelopment: () => boolean
+    devLog: (...args: any[]) => void
+  }
+}
+
+/**
+ * Initializes global devtools object (browser only)
+ *
+ * @example
+ * ```ts
+ * initGlobalDevtools()
+ * window.__GEENIUS_DEVTOOLS__.devLog('debug info')
+ * ```
+ */
+export function initGlobalDevtools() {
+  if (typeof window === 'undefined') return
+
+  const flags = new FeatureFlagManager()
+
+  ;(window as any).__GEENIUS_DEVTOOLS__ = {
+    flags,
+    isDevelopment,
+    devLog,
+    devWarn,
+    devAssert,
+  }
+}
+
+/**
+ * Initializes devtools from environment
+ * Useful for loading feature flags from build-time environment variables
+ *
+ * @example
+ * ```ts
+ * const flags = createTypedFlags<'newUI' | 'beta'>()
+ * initDevtoolsFromEnv(flags, ['FEATURE_NEW_UI', 'FEATURE_BETA'])
+ * ```
+ */
+export function initDevtoolsFromEnv<T extends string>(
+  flags: ReturnType<typeof createTypedFlags<T>>,
+  envKeys: string[]
+) {
+  for (const key of envKeys) {
+    const enabled =
+      typeof process !== 'undefined' &&
+      process.env[key] === 'true'
+
+    if (enabled) {
+      const flagName = key
+        .replace(/^FEATURE_/, '')
+        .toLowerCase() as T
+      flags.set(flagName, true)
+    }
+  }
+}

package/packages/devtools/tsup.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+    entry: {
+        index: 'src/index.ts',
+    },
+    format: ['esm'],
+    dts: true,
+    clean: true,
+    sourcemap: true,
+})
+

package/packages/env/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@geenius-tools/env",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Environment variable validation for Geenius projects",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  },
+  "dependencies": {
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "typescript": "~6.0.2",
+    "tsup": "^8.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/packages/env/src/index.ts

@@ -0,0 +1,264 @@
+/**
+ * @geenius-tools/env — Environment variable validation and management
+ *
+ * Provides schema-based environment variable validation using Zod.
+ * Validates at runtime and provides type-safe access to env vars.
+ */
+
+import { z, ZodSchema } from 'zod/v4'
+
+/**
+ * Environment variable schema definition
+ */
+export type EnvSchema = Record<string, ZodSchema>
+
+/**
+ * Configuration for environment validation
+ */
+export interface EnvConfig {
+  /** Whether to throw on validation error (default: true) */
+  throw?: boolean
+  /** Prefix to add to all env var names (e.g., 'REACT_APP_') */
+  prefix?: string
+  /** Default values for optional variables */
+  defaults?: Record<string, unknown>
+}
+
+/**
+ * Validates environment variables against a Zod schema
+ *
+ * @param schema Zod schema defining expected environment variables
+ * @param config Validation configuration options
+ * @returns Validated environment variables as typed object
+ * @throws Error if validation fails and throw option is true
+ *
+ * @example
+ * ```ts
+ * const envSchema = {
+ *   DATABASE_URL: z.string().url(),
+ *   API_KEY: z.string(),
+ *   DEBUG: z.enum(['true', 'false']).optional(),
+ * }
+ *
+ * const env = validateEnv(envSchema, { throw: true })
+ * // env is now { DATABASE_URL: string, API_KEY: string, DEBUG?: string }
+ * ```
+ */
+export function validateEnv<T extends EnvSchema>(
+  schema: T,
+  config: EnvConfig = {}
+): Partial<{ [K in keyof T]: unknown }> {
+  const { prefix = '', defaults = {}, throw: shouldThrow = true } = config
+
+  const envVars: Record<string, unknown> = {}
+
+  // Collect env variables with prefix
+  for (const key of Object.keys(schema)) {
+    const prefixedKey = prefix ? `${prefix}${key}` : key
+    const value = process.env[prefixedKey] ?? defaults[key]
+
+    if (value !== undefined) {
+      envVars[key] = value
+    }
+  }
+
+  // Validate using zod
+  const schemaObj = z.object(schema as Record<string, ZodSchema>)
+  const result = schemaObj.safeParse(envVars)
+
+  if (!result.success) {
+    const errors = result.error.errors
+      .map((e) => `${e.path.join('.')}: ${e.message}`)
+      .join(', ')
+
+    const message = `Environment validation failed: ${errors}`
+
+    if (shouldThrow) {
+      throw new Error(message)
+    }
+
+    console.error(message)
+    return {}
+  }
+
+  return result.data
+}
+
+/**
+ * Creates a reusable environment validator
+ *
+ * @param schema Zod schema
+ * @param config Default configuration
+ * @returns Validator function
+ *
+ * @example
+ * ```ts
+ * const validator = createEnvValidator(
+ *   { DATABASE_URL: z.string().url() },
+ *   { throw: true }
+ * )
+ * const env = validator()
+ * ```
+ */
+export function createEnvValidator<T extends EnvSchema>(
+  schema: T,
+  config: EnvConfig = {}
+) {
+  return () => validateEnv(schema, config)
+}
+
+/**
+ * Gets a single environment variable with optional validation
+ *
+ * @param key Environment variable key
+ * @param schema Optional Zod schema for validation
+ * @param defaultValue Default value if not found
+ * @returns Environment variable value or default
+ *
+ * @example
+ * ```ts
+ * const apiKey = getEnv('API_KEY', z.string().min(1))
+ * ```
+ */
+export function getEnv<T = string>(
+  key: string,
+  schema?: ZodSchema,
+  defaultValue?: T
+): T | undefined {
+  const value = process.env[key] ?? defaultValue
+
+  if (!value) return undefined
+
+  if (schema) {
+    const result = schema.safeParse(value)
+    if (!result.success) {
+      throw new Error(`Invalid env var ${key}: ${result.error.message}`)
+    }
+    return result.data as T
+  }
+
+  return value as T
+}
+
+/**
+ * Checks if environment variable exists and is set
+ *
+ * @param key Variable name
+ * @returns True if variable exists
+ */
+export function hasEnv(key: string): boolean {
+  return key in process.env
+}
+
+/**
+ * Gets multiple environment variables at once
+ *
+ * @param keys List of environment variable keys
+ * @returns Object with available values
+ *
+ * @example
+ * ```ts
+ * const { API_KEY, DEBUG } = getEnvs(['API_KEY', 'DEBUG'])
+ * ```
+ */
+export function getEnvs(keys: string[]): Record<string, string | undefined> {
+  return keys.reduce(
+    (acc, key) => {
+      acc[key] = process.env[key]
+      return acc
+    },
+    {} as Record<string, string | undefined>
+  )
+}
+
+/**
+ * Asserts that all required environment variables are set
+ *
+ * @param requiredKeys List of required variable names
+ * @throws Error if any required variable is missing
+ *
+ * @example
+ * ```ts
+ * requireEnv(['DATABASE_URL', 'API_KEY'])
+ * ```
+ */
+export function requireEnv(requiredKeys: string[]): void {
+  const missing = requiredKeys.filter((key) => !(key in process.env))
+
+  if (missing.length > 0) {
+    throw new Error(
+      `Missing required environment variables: ${missing.join(', ')}`
+    )
+  }
+}
+
+/**
+ * Parses environment variable as JSON
+ *
+ * @param key Environment variable key
+ * @param defaultValue Default object if parsing fails
+ * @returns Parsed JSON object
+ *
+ * @example
+ * ```ts
+ * const config = parseEnvJson('APP_CONFIG', { theme: 'light' })
+ * ```
+ */
+export function parseEnvJson<T = unknown>(
+  key: string,
+  defaultValue?: T
+): T | undefined {
+  const value = process.env[key]
+
+  if (!value) return defaultValue
+
+  try {
+    return JSON.parse(value) as T
+  } catch {
+    console.warn(`Failed to parse ${key} as JSON`)
+    return defaultValue
+  }
+}
+
+/**
+ * Parses environment variable as boolean
+ *
+ * @param key Environment variable key
+ * @param defaultValue Default value
+ * @returns Boolean value
+ *
+ * @example
+ * ```ts
+ * const debug = parseEnvBool('DEBUG', false)
+ * ```
+ */
+export function parseEnvBool(key: string, defaultValue = false): boolean {
+  const value = process.env[key]
+
+  if (!value) return defaultValue
+
+  return ['true', '1', 'yes', 'on'].includes(value.toLowerCase())
+}
+
+/**
+ * Parses environment variable as number
+ *
+ * @param key Environment variable key
+ * @param defaultValue Default value
+ * @returns Numeric value
+ *
+ * @example
+ * ```ts
+ * const port = parseEnvNumber('PORT', 3000)
+ * ```
+ */
+export function parseEnvNumber(key: string, defaultValue = 0): number {
+  const value = process.env[key]
+
+  if (!value) return defaultValue
+
+  const num = Number(value)
+  return isNaN(num) ? defaultValue : num
+}
+
+export type { ZodSchema } from 'zod/v4'

package/packages/env/tsup.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+    entry: {
+        index: 'src/index.ts',
+    },
+    format: ['esm'],
+    dts: true,
+    clean: true,
+    sourcemap: true,
+})
+

package/packages/errors/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@geenius-tools/errors",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Error handling utilities for Geenius projects",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  },
+  "devDependencies": {
+    "typescript": "~6.0.2",
+    "tsup": "^8.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}