ima-claude 2.9.0

package/plugins/ima-claude/skills/js-fp/references/performance-patterns.md

@@ -0,0 +1,116 @@
+# Performance Patterns Reference
+
+Evidence-based optimization through pure functions.
+
+## Core Formula
+
+```
+Pure Function + Closure + Pre-compilation = Exceptional Performance
+```
+
+## The Pre-Compilation Pattern
+
+**Problem**: O(records x fields) - configuration accessed every iteration
+
+```javascript
+// SLOW: 100,000 records x 24 fields = 2.4 million iterations
+function processRecords(records, schema) {
+    return records.map(record => {
+        return schema.fields.reduce((obj, field) => {
+            obj[field.name] = transformField(record[field.name], field.type)
+            return obj
+        }, {})
+    })
+}
+```
+
+**Solution**: Pre-compile configuration into closures
+
+```javascript
+// FAST: O(records + fields) - configuration extracted once
+export const mapRecord = ({prefix, fields}) => {
+    const allowedFields = Object.keys(fields)
+
+    // Return optimized mapping function
+    return (record) => {
+        const map = {}
+        allowedFields.forEach((key) => {
+            const val = record[prefix + '_' + key]
+            map[key] = fields[key].formatter ? fields[key].formatter(val) : val
+        })
+        return map
+    }
+}
+
+// Usage
+const mapper = mapRecord(meta)  // Configure once
+const objects = records.map(mapper)  // Linear performance
+```
+
+**Result**: 10-25x improvement on large datasets
+
+## Function Factory Pattern
+
+```javascript
+// Create specialized functions - configuration cost paid once
+const createValidator = (rules) => (value) => {
+  const errors = []
+  for (const rule of rules) {
+    if (!rule.validator(value)) {
+      errors.push(rule.message)
+    }
+  }
+  return errors.length === 0 ? { valid: true } : { valid: false, errors }
+}
+
+// Configure once
+const validateEmail = createValidator([
+  { validator: v => typeof v === 'string', message: 'Must be string' },
+  { validator: v => v.includes('@'), message: 'Must contain @' }
+])
+
+// Use many times (fast)
+emails.map(validateEmail)
+```
+
+## Triple-Layer Curry Pattern
+
+```
+(Configuration) => (Parameters) => (Context) => Result
+```
+
+```javascript
+export const selectUserByEmail = (meta) => (user) => async (ctx) => {
+    const sql = getSelectStmt(meta)({whereSet: [{field: 'email'}]})
+    const results = await ctx.db.query({sql, values: [user.email]})
+    return mapRecord(meta)(results[0])
+}
+
+// Layer 1: Configuration (compile-time)
+const configuredQuery = selectUserByEmail(initMeta(userMeta))
+
+// Layers 2+3: Runtime execution
+const user = await configuredQuery({email: 'test@example.com'})(context)
+```
+
+## When to Optimize
+
+1. **Measure first** - Profile before optimizing
+2. **>10K items** - Pre-compilation matters at scale
+3. **Repeated config access** - Look for nested loops accessing setup data
+4. **Hot paths** - Focus on frequently called code
+
+## When NOT to Optimize
+
+- Small datasets (<1K items)
+- One-time operations
+- Code readability suffers significantly
+- No measured performance problem
+
+## Quick Optimization Checklist
+
+1. [ ] Identify repeated configuration access in loops
+2. [ ] Extract configuration phase outside execution loop
+3. [ ] Use closures to cache configuration
+4. [ ] Verify linear execution (not quadratic)
+5. [ ] Benchmark before/after with real data

package/plugins/ima-claude/skills/js-fp/references/testing-patterns.md

@@ -0,0 +1,134 @@
+# Testing Patterns Reference
+
+Comprehensive edge-case testing enabled by pure functions.
+
+## Core Principle
+
+Test systematically against ALL data types and edge cases. Pure functions make this practical:
+- Same input always produces same output
+- No side effects - tests don't interfere
+- Fast execution - pure functions run quickly
+- Predictable behavior - easy to reason about
+
+## Test Matrix Template
+
+```javascript
+describe('FunctionUnderTest', () => {
+    describe('valid inputs', () => {
+        it('should handle expected use cases', () => {
+            expect(validateIntegerGreaterThan(0)(5)).toBe(true)
+            expect(validateIntegerGreaterThan(0)('5')).toBe(true)  // String numbers
+        })
+    })
+
+    describe('invalid types', () => {
+        // Test against ALL JavaScript types
+        it('should reject null', () => expect(fn(null)).toBe(false))
+        it('should reject undefined', () => expect(fn(undefined)).toBe(false))
+        it('should reject NaN', () => expect(fn(NaN)).toBe(false))
+        it('should reject boolean', () => expect(fn(true)).toBe(false))
+        it('should reject array', () => expect(fn([])).toBe(false))
+        it('should reject object', () => expect(fn({})).toBe(false))
+        it('should reject function', () => expect(fn(() => {})).toBe(false))
+    })
+
+    describe('edge cases', () => {
+        // Boundary values, empty inputs, extreme values
+    })
+
+    describe('composition', () => {
+        // Test function combinations
+    })
+})
+```
+
+## Parameterized Test Pattern
+
+```javascript
+describe('calculateDiscount', () => {
+  describe('valid inputs', () => {
+    const testCases = [
+      [100, 0.1, 10],
+      [50, 0.2, 10],
+      [0, 0.1, 0]
+    ]
+
+    testCases.forEach(([price, rate, expected]) => {
+      it(`${rate*100}% discount on ${price} = ${expected}`, () => {
+        expect(calculateDiscount(price, rate)).toBe(expected)
+      })
+    })
+  })
+
+  describe('invalid types', () => {
+    const invalidTypes = [null, undefined, NaN, true, [], {}, '100']
+
+    invalidTypes.forEach(input => {
+      it(`handles ${typeof input} (${String(input)}) gracefully`, () => {
+        expect(() => calculateDiscount(input, 0.1)).not.toThrow()
+        expect(calculateDiscount(input, 0.1)).toBe(0)
+      })
+    })
+  })
+})
+```
+
+## Testing Composed Functions
+
+```javascript
+describe('validateCreditCard', () => {
+  const validCard = {
+    name: 'John Doe',
+    number: '4111111111111111',
+    expDate: '12/26',
+    cvv: '123'
+  }
+
+  it('accepts valid complete card', () => {
+    expect(validateCreditCard(validCard)).toEqual({ valid: true })
+  })
+
+  // Test each field independently
+  const fields = ['name', 'number', 'expDate', 'cvv']
+  fields.forEach(field => {
+    it(`rejects missing ${field}`, () => {
+      const invalid = { ...validCard, [field]: '' }
+      expect(validateCreditCard(invalid).valid).toBe(false)
+    })
+  })
+})
+```
+
+## Testing Pure Functions with Dependencies
+
+```javascript
+// Function under test
+const saveUser = async (userData, hasher, database) => {
+  const hashedPassword = await hasher.hash(userData.password)
+  return database.save({ ...userData, password: hashedPassword })
+}
+
+// Test with mock dependencies
+describe('saveUser', () => {
+  const mockHasher = { hash: jest.fn(p => `hashed_${p}`) }
+  const mockDb = { save: jest.fn(user => ({ id: 1, ...user })) }
+
+  it('hashes password and saves user', async () => {
+    const result = await saveUser(
+      { email: 'test@example.com', password: 'secret' },
+      mockHasher,
+      mockDb
+    )
+    expect(mockHasher.hash).toHaveBeenCalledWith('secret')
+    expect(result.password).toBe('hashed_secret')
+  })
+})
+```
+
+## Quick Checklist
+
+- [ ] Test all JavaScript types (null, undefined, NaN, boolean, array, object, function)
+- [ ] Test boundary values (0, -1, MAX_SAFE_INTEGER, empty string, empty array)
+- [ ] Test composition of functions together
+- [ ] Mock dependencies for isolation
+- [ ] Use parameterized tests for data variations

package/plugins/ima-claude/skills/js-fp-api/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: "js-fp-api"
+description: "FP API patterns for Node.js with security-first SQL and middleware DI - references js-fp core"
+---
+
+# JavaScript FP - Node.js API
+
+Functional programming patterns for Node.js APIs with security-first SQL, middleware dependency injection, and self-contained routes.
+
+## When to Use This Skill
+
+- Building REST APIs with Node.js
+- Need security-first SQL patterns
+- Implementing middleware-based dependency injection
+- Self-contained route architecture
+- Testing API endpoints comprehensively
+
+## Core Philosophy
+
+**Self-contained routes** (300-500 lines max) with **security-first SQL**, **middleware DI**, and **pure business logic separation** when genuinely reusable (3+ routes).
+
+**Foundation**: This skill builds on `js-fp` core principles. Reference `../js-fp/SKILL.md` for purity, composition, dependency injection, and testing patterns.
+
+## CRITICAL: Security-First SQL (MANDATORY)
+
+**Rule**: NEVER use string concatenation for SQL. ALWAYS use parameterized queries.
+
+```javascript
+// NEVER: SQL injection vulnerability
+const sql = `SELECT * FROM events WHERE domain LIKE '%${domain}%'` // DANGER!
+
+// ALWAYS: Parameterized queries returning {sql, params}
+const buildDomainFilter = (domain) => {
+  const validation = validateDomain(domain)
+  if (!validation.valid) throw new Error(validation.error)
+  if (validation.domain === 'all') return { sql: '', params: {} }
+
+  return {
+    sql: 'AND from_address LIKE @domain_pattern',
+    params: { domain_pattern: `%${validation.domain}%` }
+  }
+}
+```
+
+**Deep Dive**: See `references/security-sql.md` for advanced SQL patterns, triple-layer curry, and domain whitelisting.
+
+## Mandatory Architecture
+
+### File Structure
+
+```
+/api/
+├── middleware/          # DI only (database.js, auth.js)
+├── shared/             # ONLY if 3+ routes use it
+│   ├── validators.js   # Domain whitelisting, validation
+│   ├── filters.js      # SQL builders returning {sql, params}
+│   └── constants.js    # Static config
+├── business/           # Pure functions ONLY (calculations, transformations)
+└── routes/
+    ├── [domain]/       # Logical grouping
+    │   ├── index.js    # Route orchestrator
+    │   └── [endpoint].js # 300-500 lines MAX
+    └── [simple].js     # Standalone endpoints
+```
+
+### Self-Contained Route Pattern (ENFORCE)
+
+```javascript
+import { Hono } from 'hono'
+import { validateDomain } from '../../shared/validators.js'
+import { buildDomainFilter } from '../../shared/filters.js'
+
+const route = new Hono()
+
+// ───── Route-scoped validation ─────
+const validateRequest = (ctx) => {
+  const domain = ctx.req.query('domain')
+  const validation = validateDomain(domain)
+  if (!validation.valid) {
+    const error = new Error(validation.error)
+    error.status = 400
+    throw error
+  }
+  return { domain: validation.domain }
+}
+
+// ───── Security-first SQL building ─────
+const buildQuery = (env, { domain }) => {
+  const table = getTableReference(env)('events')
+  const filters = buildDomainFilter(domain)
+
+  return {
+    sql: `SELECT * FROM ${table} WHERE 1=1 ${filters.sql}`,
+    params: filters.params
+  }
+}
+
+// ───── Business logic (keep in-route if <50 lines) ─────
+const processData = (raw) => raw.map(r => ({
+  ...r,
+  timestamp: r.timestamp + 'Z'
+}))
+
+// ───── Clean orchestration ─────
+route.get('/', async (c) => {
+  try {
+    const params = validateRequest(c)
+    const { sql, params: qp } = buildQuery(c.env, params)
+    const raw = await c.db.queryWithParams(sql, qp)  // Middleware-injected
+    return c.json({ success: true, data: processData(raw) })
+  } catch (error) {
+    return c.json({ success: false, error: error.message }, error.status || 500)
+  }
+})
+
+export default route
+```
+
+## Middleware Dependency Injection
+
+Inject dependencies via middleware context, not per-request instantiation.
+
+```javascript
+// middleware/database.js
+export const databaseMiddleware = async (c, next) => {
+  const db = createDatabaseClient(c.env.DATABASE_URL)
+  c.db = {
+    query: (sql) => db.query(sql),
+    queryWithParams: (sql, params) => db.query(sql, params),
+    transaction: (fn) => db.transaction(fn)
+  }
+  await next()
+}
+
+// Usage in routes: await c.db.queryWithParams(sql, params)
+```
+
+**Deep Dive**: See `references/middleware-patterns.md` for function factories, auth middleware, and testing patterns.
+
+## When to Extract to business/
+
+**Extract ONLY if**:
+- Function is genuinely reusable (3+ routes use it)
+- Pure calculation/transformation
+- No side effects
+- 100% testable
+
+```javascript
+// business/calculations.js
+export const calculateTotalRevenue = (orders) =>
+  orders.reduce((sum, order) => sum + order.total, 0)
+
+export const calculateAverageOrderValue = (orders) => {
+  if (orders.length === 0) return 0
+  return calculateTotalRevenue(orders) / orders.length
+}
+```
+
+## Anti-Patterns (REJECT)
+
+```javascript
+// Routes >500 lines → Split to business/
+// Service layer files → Keep in-route or business/
+// String concatenation SQL → Use {sql, params}
+// Manual client init → Use middleware DI
+// Validation files used by <3 routes → Keep in-route
+// Abstraction layers → Direct implementation
+// Complex error handling frameworks → Simple try/catch
+// Over-engineered logging → Simple logger DI
+```
+
+## Testing Strategy
+
+### Pure Business Logic Tests
+
+```javascript
+import { calculateTotalRevenue } from '../calculations.js'
+
+describe('calculateTotalRevenue', () => {
+  it('sums order totals', () => {
+    const orders = [{ total: 100 }, { total: 200 }, { total: 50 }]
+    expect(calculateTotalRevenue(orders)).toBe(350)
+  })
+
+  it('handles empty array', () => {
+    expect(calculateTotalRevenue([])).toBe(0)
+  })
+})
+```
+
+### Route Integration Tests
+
+```javascript
+describe('GET /orders', () => {
+  const mockDb = {
+    queryWithParams: jest.fn().mockResolvedValue([{ id: 1, total: 100 }])
+  }
+
+  it('returns orders successfully', async () => {
+    const res = await app.request('/orders', { method: 'GET' }, { db: mockDb })
+    expect(res.status).toBe(200)
+  })
+
+  it('validates required parameters', async () => {
+    const res = await app.request('/orders?domain=invalid', { method: 'GET' }, { db: mockDb })
+    expect(res.status).toBe(400)
+  })
+})
+```
+
+**Deep Dive**: See `references/middleware-patterns.md` for comprehensive testing patterns.
+
+## Quality Gates
+
+Before implementing any API endpoint:
+
+1. **Security-first SQL**: Using `{sql, params}` pattern?
+2. **Route size**: Can route be <500 lines?
+3. **Validation**: Route-scoped closures or shared (3+ routes)?
+4. **Middleware DI**: Using `c.db`, `c.bq`, `c.logger`?
+5. **Pure business logic**: Extracted if reusable (3+ routes)?
+6. **Testing**: Can inject mocks for all dependencies?
+7. **FP principles**: Pure functions, explicit dependencies?
+
+## When to Load Reference Files
+
+### Security Deep-Dive
+**File**: `references/security-sql.md`
+**Load When**:
+- Building complex multi-filter queries
+- Implementing triple-layer curry pattern
+- Training team on SQL security
+- Debugging injection vulnerabilities
+**Contains**: Parameterized queries, SQL builders, domain whitelisting, security checklist
+
+### Middleware Patterns
+**File**: `references/middleware-patterns.md`
+**Load When**:
+- Building custom middleware
+- Implementing function factories for O(1) performance
+- Setting up auth middleware
+- Writing comprehensive integration tests
+**Contains**: Context-based DI, function factories, auth patterns, testing with mocks
+
+### Validation Strategies
+**File**: `references/validation-patterns.md`
+**Load When**:
+- Implementing complex validation logic
+- Building composable validators
+- Deciding where to place validation code
+- Implementing error accumulation
+**Contains**: validateAll utility, composition patterns, result objects, when to extract
+
+### Working Examples
+**Directory**: `examples/`
+**Load When**: Need complete working API examples
+**Contains**: Full CRUD endpoints, authentication, authorization, testing
+
+## Foundation Reference
+
+**Core FP Principles**: `../js-fp/SKILL.md`
+- Purity and side effect isolation
+- Composition patterns
+- Dependency injection
+- Immutability
+- Testing strategies
+
+**Deep Dive**: `../js-fp/core-principles.md` for complete FP philosophy
+
+## Success Metrics
+
+- **Security**: Zero SQL injection vulnerabilities
+- **Testability**: 95%+ coverage for pure functions
+- **Maintainability**: Routes under 500 lines
+- **Performance**: Sub-200ms response times
+- **Code Quality**: Clear, self-documenting code
+
+## Philosophy
+
+*"Self-contained routes with security-first SQL and minimal abstraction - optimize for readability and security over clever architecture."*