@mantiq/core 0.0.1

package/src/cache/MemcachedCacheStore.ts

@@ -0,0 +1,115 @@
+import type { CacheStore } from '../contracts/Cache.ts'
+
+export interface MemcachedCacheConfig {
+  /** Comma-separated server list, e.g. "host1:11211,host2:11211" */
+  servers?: string
+  prefix?: string
+  username?: string
+  password?: string
+}
+
+/**
+ * Memcached-backed cache store using memjs.
+ *
+ * Requires `memjs` as a peer dependency:
+ *   bun add memjs
+ */
+export class MemcachedCacheStore implements CacheStore {
+  private client: any
+  private readonly prefix: string
+
+  constructor(config: MemcachedCacheConfig = {}) {
+    this.prefix = config.prefix ?? 'mantiq_cache:'
+
+    try {
+      const memjs = require('memjs')
+      this.client = memjs.Client.create(config.servers ?? '127.0.0.1:11211', {
+        username: config.username,
+        password: config.password,
+      })
+    } catch {
+      throw new Error(
+        'memjs is required for the Memcached cache driver. Install it with: bun add memjs',
+      )
+    }
+  }
+
+  async get<T = unknown>(key: string): Promise<T | undefined> {
+    const result = await this.client.get(this.prefixed(key))
+    if (!result.value) return undefined
+
+    const raw = result.value.toString()
+    try {
+      return JSON.parse(raw) as T
+    } catch {
+      return raw as T
+    }
+  }
+
+  async put(key: string, value: unknown, ttl?: number): Promise<void> {
+    const serialized = JSON.stringify(value)
+    await this.client.set(this.prefixed(key), serialized, { expires: ttl ?? 0 })
+  }
+
+  async forget(key: string): Promise<boolean> {
+    return this.client.delete(this.prefixed(key))
+  }
+
+  async has(key: string): Promise<boolean> {
+    const result = await this.client.get(this.prefixed(key))
+    return result.value !== null
+  }
+
+  async flush(): Promise<void> {
+    await this.client.flush()
+  }
+
+  async increment(key: string, value = 1): Promise<number> {
+    // Memcached INCR requires the key to exist; if it doesn't, initialize it
+    try {
+      const result = await this.client.increment(this.prefixed(key), value, { initial: value })
+      return result.value ?? value
+    } catch {
+      await this.put(key, value)
+      return value
+    }
+  }
+
+  async decrement(key: string, value = 1): Promise<number> {
+    try {
+      const result = await this.client.decrement(this.prefixed(key), value, { initial: 0 })
+      return result.value ?? 0
+    } catch {
+      await this.put(key, 0)
+      return 0
+    }
+  }
+
+  async add(key: string, value: unknown, ttl?: number): Promise<boolean> {
+    const serialized = JSON.stringify(value)
+    try {
+      await this.client.add(this.prefixed(key), serialized, { expires: ttl ?? 0 })
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Get the underlying memjs client.
+   */
+  getClient(): any {
+    return this.client
+  }
+
+  /**
+   * Close the Memcached connection.
+   */
+  async disconnect(): Promise<void> {
+    this.client.close()
+  }
+
+  private prefixed(key: string): string {
+    return this.prefix + key
+  }
+}

package/src/cache/MemoryCacheStore.ts

@@ -0,0 +1,62 @@
+import type { CacheStore } from '../contracts/Cache.ts'
+
+interface CacheEntry {
+  value: unknown
+  expiresAt: number | null // timestamp in ms, null = forever
+}
+
+/**
+ * In-memory cache store. Fast, but lost on process restart.
+ * Ideal for dev, testing, and short-lived caches.
+ */
+export class MemoryCacheStore implements CacheStore {
+  private store = new Map<string, CacheEntry>()
+
+  async get<T = unknown>(key: string): Promise<T | undefined> {
+    const entry = this.store.get(key)
+    if (!entry) return undefined
+
+    if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+      this.store.delete(key)
+      return undefined
+    }
+
+    return entry.value as T
+  }
+
+  async put(key: string, value: unknown, ttl?: number): Promise<void> {
+    this.store.set(key, {
+      value,
+      expiresAt: ttl != null ? Date.now() + ttl * 1000 : null,
+    })
+  }
+
+  async forget(key: string): Promise<boolean> {
+    return this.store.delete(key)
+  }
+
+  async has(key: string): Promise<boolean> {
+    return (await this.get(key)) !== undefined
+  }
+
+  async flush(): Promise<void> {
+    this.store.clear()
+  }
+
+  async increment(key: string, value = 1): Promise<number> {
+    const current = await this.get<number>(key)
+    const newValue = (current ?? 0) + value
+    await this.put(key, newValue)
+    return newValue
+  }
+
+  async decrement(key: string, value = 1): Promise<number> {
+    return this.increment(key, -value)
+  }
+
+  async add(key: string, value: unknown, ttl?: number): Promise<boolean> {
+    if (await this.has(key)) return false
+    await this.put(key, value, ttl)
+    return true
+  }
+}

package/src/cache/NullCacheStore.ts

@@ -0,0 +1,39 @@
+import type { CacheStore } from '../contracts/Cache.ts'
+
+/**
+ * Null cache store — never stores anything.
+ * Useful for disabling cache in testing or specific environments.
+ */
+export class NullCacheStore implements CacheStore {
+  async get<T = unknown>(_key: string): Promise<T | undefined> {
+    return undefined
+  }
+
+  async put(_key: string, _value: unknown, _ttl?: number): Promise<void> {
+    // noop
+  }
+
+  async forget(_key: string): Promise<boolean> {
+    return false
+  }
+
+  async has(_key: string): Promise<boolean> {
+    return false
+  }
+
+  async flush(): Promise<void> {
+    // noop
+  }
+
+  async increment(_key: string, value = 1): Promise<number> {
+    return value
+  }
+
+  async decrement(_key: string, value = 1): Promise<number> {
+    return -value
+  }
+
+  async add(_key: string, _value: unknown, _ttl?: number): Promise<boolean> {
+    return false
+  }
+}

package/src/cache/RedisCacheStore.ts

@@ -0,0 +1,125 @@
+import type { CacheStore } from '../contracts/Cache.ts'
+
+export interface RedisCacheConfig {
+  host?: string
+  port?: number
+  password?: string
+  db?: number
+  prefix?: string
+  url?: string
+}
+
+/**
+ * Redis-backed cache store using ioredis.
+ *
+ * Requires `ioredis` as a peer dependency:
+ *   bun add ioredis
+ */
+export class RedisCacheStore implements CacheStore {
+  private client: any
+  private readonly prefix: string
+
+  constructor(config: RedisCacheConfig = {}) {
+    this.prefix = config.prefix ?? 'mantiq_cache:'
+
+    try {
+      const Redis = require('ioredis')
+      if (config.url) {
+        this.client = new Redis(config.url)
+      } else {
+        this.client = new Redis({
+          host: config.host ?? '127.0.0.1',
+          port: config.port ?? 6379,
+          password: config.password,
+          db: config.db ?? 0,
+        })
+      }
+    } catch {
+      throw new Error(
+        'ioredis is required for the Redis cache driver. Install it with: bun add ioredis',
+      )
+    }
+  }
+
+  async get<T = unknown>(key: string): Promise<T | undefined> {
+    const raw = await this.client.get(this.prefixed(key))
+    if (raw === null) return undefined
+
+    try {
+      return JSON.parse(raw) as T
+    } catch {
+      return raw as T
+    }
+  }
+
+  async put(key: string, value: unknown, ttl?: number): Promise<void> {
+    const serialized = JSON.stringify(value)
+    if (ttl != null) {
+      await this.client.setex(this.prefixed(key), ttl, serialized)
+    } else {
+      await this.client.set(this.prefixed(key), serialized)
+    }
+  }
+
+  async forget(key: string): Promise<boolean> {
+    const count = await this.client.del(this.prefixed(key))
+    return count > 0
+  }
+
+  async has(key: string): Promise<boolean> {
+    const exists = await this.client.exists(this.prefixed(key))
+    return exists > 0
+  }
+
+  async flush(): Promise<void> {
+    const pattern = this.prefixed('*')
+    let cursor = '0'
+
+    do {
+      const [nextCursor, keys] = await this.client.scan(cursor, 'MATCH', pattern, 'COUNT', 1000)
+      cursor = nextCursor
+      if (keys.length > 0) {
+        await this.client.del(...keys)
+      }
+    } while (cursor !== '0')
+  }
+
+  async increment(key: string, value = 1): Promise<number> {
+    return this.client.incrby(this.prefixed(key), value)
+  }
+
+  async decrement(key: string, value = 1): Promise<number> {
+    return this.client.decrby(this.prefixed(key), value)
+  }
+
+  async add(key: string, value: unknown, ttl?: number): Promise<boolean> {
+    const serialized = JSON.stringify(value)
+
+    if (ttl != null) {
+      // SET key value EX ttl NX — only set if not exists
+      const result = await this.client.set(this.prefixed(key), serialized, 'EX', ttl, 'NX')
+      return result === 'OK'
+    }
+
+    const result = await this.client.set(this.prefixed(key), serialized, 'NX')
+    return result === 'OK'
+  }
+
+  /**
+   * Get the underlying ioredis client for advanced operations.
+   */
+  getClient(): any {
+    return this.client
+  }
+
+  /**
+   * Disconnect the Redis client.
+   */
+  async disconnect(): Promise<void> {
+    await this.client.quit()
+  }
+
+  private prefixed(key: string): string {
+    return this.prefix + key
+  }
+}

package/src/cache/events.ts

@@ -0,0 +1,52 @@
+import { Event } from '../contracts/EventDispatcher.ts'
+
+/**
+ * Fired when a cache key is found (cache hit).
+ */
+export class CacheHit extends Event {
+  constructor(
+    public readonly key: string,
+    public readonly value: unknown,
+    public readonly store: string,
+  ) {
+    super()
+  }
+}
+
+/**
+ * Fired when a cache key is not found (cache miss).
+ */
+export class CacheMissed extends Event {
+  constructor(
+    public readonly key: string,
+    public readonly store: string,
+  ) {
+    super()
+  }
+}
+
+/**
+ * Fired when a value is written to the cache.
+ */
+export class KeyWritten extends Event {
+  constructor(
+    public readonly key: string,
+    public readonly value: unknown,
+    public readonly ttl: number | undefined,
+    public readonly store: string,
+  ) {
+    super()
+  }
+}
+
+/**
+ * Fired when a cache key is removed.
+ */
+export class KeyForgotten extends Event {
+  constructor(
+    public readonly key: string,
+    public readonly store: string,
+  ) {
+    super()
+  }
+}

package/src/config/ConfigRepository.ts

@@ -0,0 +1,115 @@
+import type { Config } from '../contracts/Config.ts'
+import { ConfigKeyNotFoundError } from '../errors/ConfigKeyNotFoundError.ts'
+
+export class ConfigRepository implements Config {
+  private data: Record<string, any> = {}
+
+  constructor(data: Record<string, any> = {}) {
+    this.data = data
+  }
+
+  /**
+   * Get a config value using dot-notation.
+   * @throws ConfigKeyNotFoundError if key doesn't exist and no default is provided
+   */
+  get<T = any>(key: string, defaultValue?: T): T {
+    const value = this.getByDotNotation(this.data, key)
+
+    if (value === undefined) {
+      if (defaultValue !== undefined) return defaultValue
+      throw new ConfigKeyNotFoundError(key)
+    }
+
+    return value as T
+  }
+
+  set(key: string, value: any): void {
+    this.setByDotNotation(this.data, key, value)
+  }
+
+  has(key: string): boolean {
+    return this.getByDotNotation(this.data, key) !== undefined
+  }
+
+  all(): Record<string, any> {
+    return { ...this.data }
+  }
+
+  /**
+   * Load config from a directory of TypeScript/JS config files.
+   * Each file's default export becomes a top-level key named after the file.
+   */
+  static async fromDirectory(configPath: string): Promise<ConfigRepository> {
+    const data: Record<string, any> = {}
+
+    try {
+      const glob = new Bun.Glob('*.ts')
+      for await (const file of glob.scan(configPath)) {
+        const key = file.replace(/\.ts$/, '')
+        try {
+          const mod = await import(`${configPath}/${file}`)
+          data[key] = mod.default ?? mod
+        } catch {
+          // Skip files that fail to load
+        }
+      }
+    } catch {
+      // Config directory doesn't exist — use empty config
+    }
+
+    return new ConfigRepository(data)
+  }
+
+  /**
+   * Load from a cached JSON file (production optimization).
+   */
+  static fromCache(cachePath: string): ConfigRepository {
+    try {
+      const file = Bun.file(cachePath)
+      const json = JSON.parse(new TextDecoder().decode(file.arrayBuffer() as any))
+      return new ConfigRepository(json)
+    } catch {
+      return new ConfigRepository()
+    }
+  }
+
+  // ── Private ───────────────────────────────────────────────────────────────
+
+  private getByDotNotation(obj: Record<string, any>, key: string): any {
+    if (!key.includes('.')) {
+      return obj[key]
+    }
+
+    const parts = key.split('.')
+    let current: any = obj
+
+    for (const part of parts) {
+      if (current === null || current === undefined || typeof current !== 'object') {
+        return undefined
+      }
+      current = current[part]
+    }
+
+    return current
+  }
+
+  private setByDotNotation(obj: Record<string, any>, key: string, value: any): void {
+    if (!key.includes('.')) {
+      obj[key] = value
+      return
+    }
+
+    const parts = key.split('.')
+    let current = obj
+
+    for (let i = 0; i < parts.length - 1; i++) {
+      const part = parts[i]!
+      if (current[part] === undefined || typeof current[part] !== 'object') {
+        current[part] = {}
+      }
+      current = current[part]
+    }
+
+    current[parts[parts.length - 1]!] = value
+  }
+}

package/src/config/env.ts

@@ -0,0 +1,26 @@
+/**
+ * Read an environment variable with type coercion.
+ *
+ * Type coercion rules:
+ * - 'true' / 'false' → boolean
+ * - '' (empty string) → '' (not undefined)
+ * - undefined → defaultValue
+ * - All other strings remain strings
+ *
+ * @example env('APP_DEBUG', false)
+ * @example env('APP_NAME', 'MantiqJS')
+ */
+export function env<T = string>(key: string, defaultValue?: T): T {
+  const raw = process.env[key]
+
+  if (raw === undefined) {
+    if (defaultValue !== undefined) return defaultValue
+    return undefined as unknown as T
+  }
+
+  // Boolean coercion
+  if (raw === 'true') return true as unknown as T
+  if (raw === 'false') return false as unknown as T
+
+  return raw as unknown as T
+}