@mantiq/core 0.0.1

package/README.md

@@ -0,0 +1,19 @@
+# @mantiq/core
+
+The foundation of MantiqJS — service container, router, middleware, HTTP kernel, config, encryption, hashing, caching, and sessions.
+
+Part of [MantiqJS](https://github.com/abdullahkhan/mantiq) — a batteries-included TypeScript web framework for Bun.
+
+## Installation
+
+```bash
+bun add @mantiq/core
+```
+
+## Documentation
+
+See the [MantiqJS repository](https://github.com/abdullahkhan/mantiq) for full documentation.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@mantiq/core",
+  "version": "0.0.1",
+  "description": "Service container, router, middleware, HTTP kernel, config, and exception handler",
+  "type": "module",
+  "license": "MIT",
+  "author": "Abdullah Khan",
+  "homepage": "https://github.com/abdullahkhan/mantiq/tree/main/packages/core",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/abdullahkhan/mantiq.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/abdullahkhan/mantiq/issues"
+  },
+  "keywords": [
+    "mantiq",
+    "mantiqjs",
+    "bun",
+    "typescript",
+    "framework",
+    "core"
+  ],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src/",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "bun": ">=1.1.0",
+    "ioredis": ">=5.0.0",
+    "memjs": ">=1.3.0"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": true
+    },
+    "memjs": {
+      "optional": true
+    }
+  }
+}

package/src/application/Application.ts

@@ -0,0 +1,241 @@
+import { ContainerImpl } from '../container/Container.ts'
+import { ConfigRepository } from '../config/ConfigRepository.ts'
+import { ContainerResolutionError } from '../errors/ContainerResolutionError.ts'
+import type { ServiceProvider } from '../contracts/ServiceProvider.ts'
+import type { Bindable, Constructor } from '../contracts/Container.ts'
+
+/**
+ * The Application is the heart of MantiqJS.
+ *
+ * It extends the service container and owns:
+ * - Config loading (always happens before any provider runs)
+ * - Provider registration + boot lifecycle
+ * - Deferred provider resolution
+ * - The global singleton accessible via app()
+ *
+ * Boot sequence:
+ *   const app = await Application.create('config/')
+ *   await app.registerProviders([...])
+ *   await app.bootProviders()
+ *   await app.make(HttpKernel).start()
+ */
+export class Application extends ContainerImpl {
+  /** The global singleton instance — set once at bootstrap. */
+  private static _instance: Application | null = null
+
+  private providers: ServiceProvider[] = []
+  private deferredProviders = new Map<Bindable<any>, ServiceProvider>()
+  private booted = false
+
+  private constructor(private readonly basePath: string = process.cwd()) {
+    super()
+    // Register the application itself so it can be resolved from the container
+    this.instance(Application, this)
+  }
+
+  // ── Singleton access ──────────────────────────────────────────────────────
+
+  /**
+   * Create and configure the application.
+   * Loads config immediately so config() is available before any provider runs.
+   *
+   * @param basePath - Project root directory
+   * @param configPath - Path to config directory (relative to basePath)
+   */
+  static async create(
+    basePath: string = process.cwd(),
+    configPath: string = 'config',
+  ): Promise<Application> {
+    const app = new Application(basePath)
+    await app.loadConfig(configPath)
+    Application._instance = app
+    return app
+  }
+
+  /**
+   * Return the global Application instance.
+   * @throws Error if the application has not been created yet.
+   */
+  static getInstance(): Application {
+    if (!Application._instance) {
+      throw new Error(
+        'Application has not been created. Call Application.create() first.',
+      )
+    }
+    return Application._instance
+  }
+
+  /**
+   * Set the global instance (useful for testing).
+   */
+  static setInstance(app: Application): void {
+    Application._instance = app
+  }
+
+  /**
+   * Destroy the global instance (useful for testing).
+   */
+  static resetInstance(): void {
+    Application._instance = null
+  }
+
+  // ── Config ────────────────────────────────────────────────────────────────
+
+  /**
+   * Load config files from the given directory.
+   * Config is available immediately after this call via config() and app.make(ConfigRepository).
+   *
+   * Falls back to a cached config file at bootstrap/cache/config.json if present.
+   */
+  async loadConfig(configDir: string): Promise<void> {
+    const cachePath = `${this.basePath}/bootstrap/cache/config.json`
+    let config: ConfigRepository
+
+    // Check for cached config first (production optimization)
+    try {
+      const cacheFile = Bun.file(cachePath)
+      if (await cacheFile.exists()) {
+        const data = await cacheFile.json()
+        config = new ConfigRepository(data)
+        this.instance(ConfigRepository, config)
+        return
+      }
+    } catch {
+      // No cache — load from files
+    }
+
+    const fullConfigPath = configDir.startsWith('/')
+      ? configDir
+      : `${this.basePath}/${configDir}`
+
+    config = await ConfigRepository.fromDirectory(fullConfigPath)
+    this.instance(ConfigRepository, config)
+  }
+
+  /**
+   * Get the config repository directly (no container lookup overhead).
+   */
+  config(): ConfigRepository {
+    return this.make(ConfigRepository)
+  }
+
+  // ── Base path helpers ─────────────────────────────────────────────────────
+
+  basePath_(path: string = ''): string {
+    return path ? `${this.basePath}/${path}` : this.basePath
+  }
+
+  configPath(path: string = ''): string {
+    return this.basePath_(path ? `config/${path}` : 'config')
+  }
+
+  storagePath(path: string = ''): string {
+    return this.basePath_(path ? `storage/${path}` : 'storage')
+  }
+
+  // ── Provider lifecycle ────────────────────────────────────────────────────
+
+  /**
+   * Register all service providers.
+   * - Deferred providers are indexed but not registered until their bindings are first resolved.
+   * - All non-deferred register() calls complete before any boot() is called.
+   */
+  async registerProviders(providerClasses: Constructor<ServiceProvider>[]): Promise<void> {
+    const nonDeferred: ServiceProvider[] = []
+
+    for (const ProviderClass of providerClasses) {
+      const provider = new ProviderClass(this)
+
+      if (provider.deferred) {
+        // Index by every binding this provider offers
+        for (const binding of provider.provides()) {
+          this.deferredProviders.set(binding, provider)
+        }
+      } else {
+        await provider.register()
+        nonDeferred.push(provider)
+      }
+    }
+
+    this.providers = nonDeferred
+  }
+
+  /**
+   * Boot all registered (non-deferred) providers.
+   * Called after ALL providers have been registered.
+   */
+  async bootProviders(): Promise<void> {
+    for (const provider of this.providers) {
+      await provider.boot()
+    }
+    this.booted = true
+  }
+
+  /**
+   * Register a single provider immediately (after initial boot).
+   * Useful for testing and dynamic provider loading.
+   */
+  async register(ProviderClass: Constructor<ServiceProvider>): Promise<void> {
+    const provider = new ProviderClass(this)
+    await provider.register()
+    if (this.booted) {
+      await provider.boot()
+    } else {
+      this.providers.push(provider)
+    }
+  }
+
+  // ── Deferred provider resolution ──────────────────────────────────────────
+
+  /**
+   * Override make() to handle deferred provider loading.
+   * If a binding isn't found in the container, check deferred providers.
+   */
+  make<T>(abstract: Bindable<T>): T {
+    try {
+      return super.make(abstract)
+    } catch (err) {
+      if (
+        err instanceof ContainerResolutionError &&
+        err.reason === 'not_bound'
+      ) {
+        const deferredProvider = this.deferredProviders.get(abstract)
+        if (deferredProvider) {
+          // Remove from deferred map so we don't loop
+          for (const [key, p] of this.deferredProviders.entries()) {
+            if (p === deferredProvider) this.deferredProviders.delete(key)
+          }
+          // Register + boot the deferred provider now
+          const boot = async () => {
+            await deferredProvider.register()
+            await deferredProvider.boot()
+            this.providers.push(deferredProvider)
+          }
+          // @internal: sync wrapper — deferred providers must not have async register/boot
+          // that relies on other async operations. In practice this is fine.
+          void boot()
+          return super.make(abstract)
+        }
+      }
+      throw err
+    }
+  }
+
+  // ── Environment ───────────────────────────────────────────────────────────
+
+  environment(): string {
+    return process.env['APP_ENV'] ?? 'production'
+  }
+
+  isLocal(): boolean {
+    return this.environment() === 'local'
+  }
+
+  isProduction(): boolean {
+    return this.environment() === 'production'
+  }
+
+  isDebug(): boolean {
+    return process.env['APP_DEBUG'] === 'true'
+  }
+}

package/src/cache/CacheManager.ts

@@ -0,0 +1,180 @@
+import type { CacheStore } from '../contracts/Cache.ts'
+import type { DriverManager } from '../contracts/DriverManager.ts'
+import type { EventDispatcher } from '../contracts/EventDispatcher.ts'
+import { MemoryCacheStore } from './MemoryCacheStore.ts'
+import { FileCacheStore } from './FileCacheStore.ts'
+import { NullCacheStore } from './NullCacheStore.ts'
+import { CacheHit, CacheMissed, KeyWritten, KeyForgotten } from './events.ts'
+import type { RedisCacheConfig } from './RedisCacheStore.ts'
+import type { MemcachedCacheConfig } from './MemcachedCacheStore.ts'
+
+export interface CacheConfig {
+  default: string
+  prefix?: string
+  stores: {
+    memory?: Record<string, unknown>
+    file?: { path: string }
+    redis?: RedisCacheConfig
+    memcached?: MemcachedCacheConfig
+    null?: Record<string, unknown>
+    [name: string]: Record<string, unknown> | RedisCacheConfig | MemcachedCacheConfig | undefined
+  }
+}
+
+/**
+ * Multi-driver cache manager (Laravel-style).
+ *
+ * Built-in drivers: memory, file, redis, memcached, null.
+ * Custom drivers can be added via `extend()`.
+ */
+export class CacheManager implements DriverManager<CacheStore>, CacheStore {
+  private readonly config: CacheConfig
+  private readonly stores = new Map<string, CacheStore>()
+  private readonly customCreators = new Map<string, () => CacheStore>()
+
+  /** Optional event dispatcher. Set by @mantiq/events when installed. */
+  static _dispatcher: EventDispatcher | null = null
+
+  constructor(config?: Partial<CacheConfig>) {
+    this.config = {
+      default: config?.default ?? 'memory',
+      stores: config?.stores ?? {},
+    }
+  }
+
+  // ── DriverManager ───────────────────────────────────────────────────────
+
+  driver(name?: string): CacheStore {
+    const storeName = name ?? this.getDefaultDriver()
+
+    if (!this.stores.has(storeName)) {
+      this.stores.set(storeName, this.createDriver(storeName))
+    }
+
+    return this.stores.get(storeName)!
+  }
+
+  /** Alias for `driver()` — Laravel compatibility. */
+  store(name?: string): CacheStore {
+    return this.driver(name)
+  }
+
+  extend(name: string, factory: () => CacheStore): void {
+    this.customCreators.set(name, factory)
+  }
+
+  getDefaultDriver(): string {
+    return this.config.default
+  }
+
+  // ── CacheStore (delegates to default store) ─────────────────────────────
+
+  async get<T = unknown>(key: string): Promise<T | undefined> {
+    const value = await this.driver().get<T>(key)
+    const storeName = this.getDefaultDriver()
+    if (value !== undefined) {
+      await CacheManager._dispatcher?.emit(new CacheHit(key, value, storeName))
+    } else {
+      await CacheManager._dispatcher?.emit(new CacheMissed(key, storeName))
+    }
+    return value
+  }
+
+  async put(key: string, value: unknown, ttl?: number): Promise<void> {
+    await this.driver().put(key, value, ttl)
+    await CacheManager._dispatcher?.emit(new KeyWritten(key, value, ttl, this.getDefaultDriver()))
+  }
+
+  async forget(key: string): Promise<boolean> {
+    const result = await this.driver().forget(key)
+    await CacheManager._dispatcher?.emit(new KeyForgotten(key, this.getDefaultDriver()))
+    return result
+  }
+
+  async has(key: string): Promise<boolean> {
+    return this.driver().has(key)
+  }
+
+  async flush(): Promise<void> {
+    return this.driver().flush()
+  }
+
+  async increment(key: string, value = 1): Promise<number> {
+    return this.driver().increment(key, value)
+  }
+
+  async decrement(key: string, value = 1): Promise<number> {
+    return this.driver().decrement(key, value)
+  }
+
+  async add(key: string, value: unknown, ttl?: number): Promise<boolean> {
+    return this.driver().add(key, value, ttl)
+  }
+
+  // ── Convenience methods ───────────────────────────────────────────────
+
+  /**
+   * Get an item from the cache, or execute the given callback and store the result.
+   */
+  async remember<T = unknown>(key: string, ttl: number | undefined, callback: () => T | Promise<T>): Promise<T> {
+    const cached = await this.get<T>(key)
+    if (cached !== undefined) return cached
+
+    const value = await callback()
+    await this.put(key, value, ttl)
+    return value
+  }
+
+  /**
+   * Get an item from the cache, or execute the given callback and store the result forever.
+   */
+  async rememberForever<T = unknown>(key: string, callback: () => T | Promise<T>): Promise<T> {
+    return this.remember<T>(key, undefined, callback)
+  }
+
+  /**
+   * Retrieve an item from the cache and delete it.
+   */
+  async pull<T = unknown>(key: string): Promise<T | undefined> {
+    const value = await this.get<T>(key)
+    if (value !== undefined) {
+      await this.forget(key)
+    }
+    return value
+  }
+
+  /**
+   * Store an item in the cache indefinitely.
+   */
+  async forever(key: string, value: unknown): Promise<void> {
+    return this.put(key, value)
+  }
+
+  // ── Internal ────────────────────────────────────────────────────────────
+
+  private createDriver(name: string): CacheStore {
+    const custom = this.customCreators.get(name)
+    if (custom) return custom()
+
+    const storeConfig = this.config.stores[name] ?? {}
+
+    switch (name) {
+      case 'memory':
+        return new MemoryCacheStore()
+      case 'file':
+        return new FileCacheStore((storeConfig as { path?: string }).path ?? '/tmp/mantiq-cache')
+      case 'redis': {
+        const { RedisCacheStore } = require('./RedisCacheStore.ts')
+        return new RedisCacheStore(storeConfig as RedisCacheConfig)
+      }
+      case 'memcached': {
+        const { MemcachedCacheStore } = require('./MemcachedCacheStore.ts')
+        return new MemcachedCacheStore(storeConfig as MemcachedCacheConfig)
+      }
+      case 'null':
+        return new NullCacheStore()
+      default:
+        throw new Error(`Unsupported cache driver: ${name}. Use extend() to register custom drivers.`)
+    }
+  }
+}

package/src/cache/FileCacheStore.ts

@@ -0,0 +1,113 @@
+import type { CacheStore } from '../contracts/Cache.ts'
+import { join } from 'node:path'
+import { mkdir, rm, readdir } from 'node:fs/promises'
+
+interface FileCachePayload {
+  value: unknown
+  expiresAt: number | null
+}
+
+/**
+ * File-based cache store. Survives process restarts.
+ * Each key maps to a JSON file in the configured directory.
+ */
+export class FileCacheStore implements CacheStore {
+  private readonly directory: string
+  private initialized = false
+
+  constructor(directory: string) {
+    this.directory = directory
+  }
+
+  async get<T = unknown>(key: string): Promise<T | undefined> {
+    await this.ensureDirectory()
+    const file = Bun.file(this.path(key))
+
+    if (!(await file.exists())) return undefined
+
+    try {
+      const payload: FileCachePayload = await file.json()
+
+      if (payload.expiresAt !== null && Date.now() > payload.expiresAt) {
+        await this.forget(key)
+        return undefined
+      }
+
+      return payload.value as T
+    } catch {
+      // Corrupted file — remove it
+      await this.forget(key)
+      return undefined
+    }
+  }
+
+  async put(key: string, value: unknown, ttl?: number): Promise<void> {
+    await this.ensureDirectory()
+    const payload: FileCachePayload = {
+      value,
+      expiresAt: ttl != null ? Date.now() + ttl * 1000 : null,
+    }
+    await Bun.write(this.path(key), JSON.stringify(payload))
+  }
+
+  async forget(key: string): Promise<boolean> {
+    try {
+      const file = Bun.file(this.path(key))
+      if (await file.exists()) {
+        await rm(this.path(key))
+        return true
+      }
+      return false
+    } catch {
+      return false
+    }
+  }
+
+  async has(key: string): Promise<boolean> {
+    return (await this.get(key)) !== undefined
+  }
+
+  async flush(): Promise<void> {
+    try {
+      const files = await readdir(this.directory)
+      await Promise.all(
+        files
+          .filter((f) => f.endsWith('.cache'))
+          .map((f) => rm(join(this.directory, f))),
+      )
+    } catch {
+      // Directory might not exist yet — that's fine
+    }
+  }
+
+  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
+  }
+
+  // ── Internal ────────────────────────────────────────────────────────────
+
+  private path(key: string): string {
+    // Hash the key to avoid filesystem issues with special characters
+    const safe = Buffer.from(key).toString('hex')
+    return join(this.directory, `${safe}.cache`)
+  }
+
+  private async ensureDirectory(): Promise<void> {
+    if (this.initialized) return
+    await mkdir(this.directory, { recursive: true })
+    this.initialized = true
+  }
+}