@mantiq/core 0.0.1

package/src/container/Container.ts

@@ -0,0 +1,198 @@
+import type { Bindable, Container, Constructor, Resolvable } from '../contracts/Container.ts'
+import { ContainerResolutionError } from '../errors/ContainerResolutionError.ts'
+import { ContextualBindingBuilder } from './ContextualBindingBuilder.ts'
+
+type Binding<T> = {
+  concrete: Resolvable<T>
+  singleton: boolean
+}
+
+export class ContainerImpl implements Container {
+  private bindings = new Map<Bindable<any>, Binding<any>>()
+  private instances = new Map<Bindable<any>, any>()
+  private aliases = new Map<string | symbol, Bindable<any>>()
+  /** contextual[concrete][abstract] = resolvable */
+  private contextual = new Map<Constructor<any>, Map<Bindable<any>, Resolvable<any>>>()
+  /** Track resolution stack for circular dependency detection */
+  private resolving = new Set<Bindable<any>>()
+
+  // ── Registration ──────────────────────────────────────────────────────────
+
+  bind<T>(abstract: Bindable<T>, concrete: Resolvable<T>): void {
+    this.bindings.set(abstract, { concrete, singleton: false })
+    // Clear any cached singleton instance if re-binding
+    this.instances.delete(abstract)
+  }
+
+  singleton<T>(abstract: Bindable<T>, concrete: Resolvable<T>): void {
+    this.bindings.set(abstract, { concrete, singleton: true })
+    this.instances.delete(abstract)
+  }
+
+  instance<T>(abstract: Bindable<T>, instance: T): void {
+    this.instances.set(abstract, instance)
+  }
+
+  // ── Resolution ────────────────────────────────────────────────────────────
+
+  make<T>(abstract: Bindable<T>): T {
+    // Resolve aliases
+    const resolved = this.resolveAlias(abstract)
+
+    // Return cached singleton instance
+    if (this.instances.has(resolved)) {
+      return this.instances.get(resolved) as T
+    }
+
+    // Detect circular dependencies
+    if (this.resolving.has(resolved)) {
+      throw new ContainerResolutionError(
+        resolved,
+        'circular_dependency',
+        `Circular dependency detected while resolving ${String(resolved)}`,
+      )
+    }
+
+    this.resolving.add(resolved)
+
+    try {
+      const binding = this.bindings.get(resolved)
+
+      let instance: T
+
+      if (binding) {
+        instance = this.build<T>(binding.concrete)
+
+        if (binding.singleton) {
+          this.instances.set(resolved, instance)
+        }
+      } else if (typeof resolved === 'function') {
+        // Auto-resolution: try to instantiate the class directly
+        instance = this.autoResolve<T>(resolved as Constructor<T>)
+      } else {
+        throw new ContainerResolutionError(
+          resolved,
+          'not_bound',
+          `No binding found for '${String(resolved)}'`,
+        )
+      }
+
+      return instance
+    } finally {
+      this.resolving.delete(resolved)
+    }
+  }
+
+  makeOrDefault<T>(abstract: Bindable<T>, defaultValue: T): T {
+    try {
+      return this.make(abstract)
+    } catch {
+      return defaultValue
+    }
+  }
+
+  has(abstract: Bindable<any>): boolean {
+    const resolved = this.resolveAlias(abstract)
+    return this.bindings.has(resolved) || this.instances.has(resolved)
+  }
+
+  // ── Contextual Binding ────────────────────────────────────────────────────
+
+  when(concrete: Constructor<any>): ContextualBindingBuilder {
+    return new ContextualBindingBuilder(concrete, (abstract, resolvable) => {
+      if (!this.contextual.has(concrete)) {
+        this.contextual.set(concrete, new Map())
+      }
+      this.contextual.get(concrete)!.set(abstract, resolvable)
+    })
+  }
+
+  // ── Aliases ───────────────────────────────────────────────────────────────
+
+  alias(abstract: Bindable<any>, alias: string | symbol): void {
+    this.aliases.set(alias, abstract)
+  }
+
+  // ── Flush ─────────────────────────────────────────────────────────────────
+
+  flush(): void {
+    this.bindings.clear()
+    this.instances.clear()
+    this.aliases.clear()
+    this.contextual.clear()
+    this.resolving.clear()
+  }
+
+  // ── Method injection ──────────────────────────────────────────────────────
+
+  call<T>(target: object, method: string, extraParams?: Record<string, any>): T {
+    const fn = (target as any)[method]
+    if (typeof fn !== 'function') {
+      throw new ContainerResolutionError(
+        method,
+        'not_bound',
+        `Method '${method}' does not exist on target`,
+      )
+    }
+    // @internal: Basic call without deep reflection; packages can override if needed
+    const params = extraParams ? Object.values(extraParams) : []
+    return fn.apply(target, params) as T
+  }
+
+  // ── Private helpers ───────────────────────────────────────────────────────
+
+  private resolveAlias(abstract: Bindable<any>): Bindable<any> {
+    if (typeof abstract === 'string' || typeof abstract === 'symbol') {
+      return this.aliases.get(abstract as string | symbol) ?? abstract
+    }
+    return abstract
+  }
+
+  private build<T>(concrete: Resolvable<T>): T {
+    if (typeof concrete === 'function' && concrete.prototype === undefined) {
+      // Arrow function / factory
+      return (concrete as (c: Container) => T)(this)
+    }
+
+    if (typeof concrete === 'function') {
+      const ctor = concrete as Constructor<T>
+      // Check if it looks like a factory (no prototype.constructor === Function means arrow)
+      try {
+        return this.autoResolve(ctor)
+      } catch {
+        // If autoResolve fails, try calling as factory
+        return (concrete as (c: Container) => T)(this)
+      }
+    }
+
+    return (concrete as (c: Container) => T)(this)
+  }
+
+  private autoResolve<T>(ctor: Constructor<T>, parentCtor?: Constructor<any>): T {
+    // Try instantiating with no args first (common case)
+    try {
+      // Check for contextual bindings if we have a parent
+      const contextMap = parentCtor ? this.contextual.get(parentCtor) : undefined
+
+      // Attempt construction. For classes with required deps this will fail
+      // but we attempt it for zero-dep classes.
+      if (ctor.length === 0) {
+        return new ctor()
+      }
+
+      // If we can't auto-resolve (no metadata), throw clearly
+      throw new ContainerResolutionError(
+        ctor,
+        'unresolvable_parameter',
+        `'${ctor.name}' has ${ctor.length} constructor parameter(s) that cannot be auto-resolved. Register an explicit binding.`,
+      )
+    } catch (err) {
+      if (err instanceof ContainerResolutionError) throw err
+      throw new ContainerResolutionError(
+        ctor,
+        'unresolvable_parameter',
+        String(err),
+      )
+    }
+  }
+}

package/src/container/ContextualBindingBuilder.ts

@@ -0,0 +1,21 @@
+import type { Bindable, Resolvable } from '../contracts/Container.ts'
+
+type GiveFn = (abstract: Bindable<any>, concrete: Resolvable<any>) => void
+
+export class ContextualBindingBuilder {
+  private needsAbstract!: Bindable<any>
+
+  constructor(
+    private readonly concrete: new (...args: any[]) => any,
+    private readonly giveFn: GiveFn,
+  ) {}
+
+  needs<T>(abstract: Bindable<T>): { give<U extends T>(concrete: Resolvable<U>): void } {
+    this.needsAbstract = abstract
+    return {
+      give: <U>(concrete: Resolvable<U>) => {
+        this.giveFn(this.needsAbstract, concrete as Resolvable<any>)
+      },
+    }
+  }
+}

package/src/contracts/Cache.ts

@@ -0,0 +1,49 @@
+/**
+ * Contract for cache store implementations.
+ */
+export interface CacheStore {
+  /**
+   * Retrieve an item from the cache.
+   * Returns `undefined` if not found or expired.
+   */
+  get<T = unknown>(key: string): Promise<T | undefined>
+
+  /**
+   * Store an item in the cache.
+   * @param ttl Time-to-live in seconds. `undefined` = forever.
+   */
+  put(key: string, value: unknown, ttl?: number): Promise<void>
+
+  /**
+   * Remove an item from the cache.
+   */
+  forget(key: string): Promise<boolean>
+
+  /**
+   * Check if an item exists (and is not expired).
+   */
+  has(key: string): Promise<boolean>
+
+  /**
+   * Remove all items from the cache.
+   */
+  flush(): Promise<void>
+
+  /**
+   * Increment a numeric value in the cache.
+   * Returns the new value.
+   */
+  increment(key: string, value?: number): Promise<number>
+
+  /**
+   * Decrement a numeric value in the cache.
+   * Returns the new value.
+   */
+  decrement(key: string, value?: number): Promise<number>
+
+  /**
+   * Store an item in the cache if the key does not already exist.
+   * Returns true if the value was stored, false if key already exists.
+   */
+  add(key: string, value: unknown, ttl?: number): Promise<boolean>
+}

package/src/contracts/Config.ts

@@ -0,0 +1,24 @@
+export interface Config {
+  /**
+   * Get a config value using dot-notation.
+   * @param key - Dot-notation key: 'database.connections.sqlite.path'
+   * @param defaultValue - Returned if key doesn't exist
+   * @throws ConfigKeyNotFoundError if key doesn't exist and no default provided
+   */
+  get<T = any>(key: string, defaultValue?: T): T
+
+  /**
+   * Set a config value at runtime (not persisted).
+   */
+  set(key: string, value: any): void
+
+  /**
+   * Check if a key exists.
+   */
+  has(key: string): boolean
+
+  /**
+   * Get all config as a flat object.
+   */
+  all(): Record<string, any>
+}

package/src/contracts/Container.ts

@@ -0,0 +1,68 @@
+export type Constructor<T = any> = new (...args: any[]) => T
+export type Bindable<T = any> = Constructor<T> | symbol | string
+export type Resolvable<T = any> = Constructor<T> | ((container: Container) => T)
+
+export interface ContextualBindingBuilder {
+  needs<T>(abstract: Bindable<T>): { give<U extends T>(concrete: Resolvable<U>): void }
+}
+
+export interface Container {
+  /**
+   * Register a transient binding. A new instance is created on each resolve.
+   * @param abstract - The interface/class/symbol to bind
+   * @param concrete - The implementation class or factory function
+   */
+  bind<T>(abstract: Bindable<T>, concrete: Resolvable<T>): void
+
+  /**
+   * Register a singleton binding. Created once, cached forever.
+   * @param abstract - The interface/class/symbol to bind
+   * @param concrete - The implementation class or factory function
+   */
+  singleton<T>(abstract: Bindable<T>, concrete: Resolvable<T>): void
+
+  /**
+   * Register an existing instance as a singleton.
+   * @param abstract - The interface/class/symbol to bind
+   * @param instance - The pre-created instance
+   */
+  instance<T>(abstract: Bindable<T>, instance: T): void
+
+  /**
+   * Resolve a binding from the container.
+   * @param abstract - The interface/class/symbol to resolve
+   * @throws ContainerResolutionError if the binding can't be resolved
+   */
+  make<T>(abstract: Bindable<T>): T
+
+  /**
+   * Resolve a binding, or return the default if not bound.
+   */
+  makeOrDefault<T>(abstract: Bindable<T>, defaultValue: T): T
+
+  /**
+   * Check if a binding exists.
+   */
+  has(abstract: Bindable<any>): boolean
+
+  /**
+   * Start building a contextual binding.
+   * @example container.when(UserController).needs(Logger).give(UserLogger)
+   */
+  when(concrete: Constructor<any>): ContextualBindingBuilder
+
+  /**
+   * Register an alias for an abstract.
+   */
+  alias(abstract: Bindable<any>, alias: string | symbol): void
+
+  /**
+   * Remove all bindings and cached instances.
+   */
+  flush(): void
+
+  /**
+   * Call a method on an object, injecting its dependencies.
+   */
+  call<T>(target: object, method: string, extraParams?: Record<string, any>): T
+}

package/src/contracts/DriverManager.ts

@@ -0,0 +1,16 @@
+export interface DriverManager<T> {
+  /**
+   * Get a driver instance by name. Returns the default driver if omitted.
+   */
+  driver(name?: string): T
+
+  /**
+   * Register a custom driver factory.
+   */
+  extend(name: string, factory: () => T): void
+
+  /**
+   * Returns the configured default driver name.
+   */
+  getDefaultDriver(): string
+}

package/src/contracts/Encrypter.ts

@@ -0,0 +1,32 @@
+/**
+ * Contract for encryption services.
+ *
+ * All implementations must provide symmetric encrypt/decrypt using
+ * a consistent serialization format.
+ */
+export interface Encrypter {
+  /**
+   * Encrypt a string value.
+   */
+  encrypt(value: string): Promise<string>
+
+  /**
+   * Decrypt a string value.
+   */
+  decrypt(encrypted: string): Promise<string>
+
+  /**
+   * Encrypt a value (serialized as JSON).
+   */
+  encryptObject(value: unknown): Promise<string>
+
+  /**
+   * Decrypt and deserialize a JSON value.
+   */
+  decryptObject<T = unknown>(encrypted: string): Promise<T>
+
+  /**
+   * Get the encryption key.
+   */
+  getKey(): CryptoKey | ArrayBuffer
+}

package/src/contracts/EventDispatcher.ts

@@ -0,0 +1,32 @@
+import type { Constructor } from './Container.ts'
+
+export abstract class Event {
+  readonly timestamp: Date = new Date()
+}
+
+export abstract class Listener {
+  abstract handle(event: Event): void | Promise<void>
+
+  shouldQueue: boolean = false
+  queue?: string
+  connection?: string
+}
+
+export type EventHandler = (event: Event) => void | Promise<void>
+
+export interface EventDispatcher {
+  /**
+   * Dispatch an event to all registered listeners.
+   */
+  emit(event: Event): Promise<void>
+
+  /**
+   * Register a listener for an event class.
+   */
+  on(eventClass: Constructor<Event>, listener: Constructor<Listener> | EventHandler): void
+
+  /**
+   * Remove all listeners for an event class.
+   */
+  forget(eventClass: Constructor<Event>): void
+}

package/src/contracts/ExceptionHandler.ts

@@ -0,0 +1,20 @@
+import type { Constructor } from './Container.ts'
+import type { MantiqRequest } from './Request.ts'
+
+export interface ExceptionHandler {
+  /**
+   * Report the exception (log it, send to error tracker, etc.).
+   * Called for every exception unless it's in the dontReport list.
+   */
+  report(error: Error): Promise<void>
+
+  /**
+   * Render the exception as an HTTP response.
+   */
+  render(request: MantiqRequest, error: unknown): Response
+
+  /**
+   * Exception classes that should not be reported (e.g., 404s).
+   */
+  dontReport: Constructor<Error>[]
+}

package/src/contracts/Hasher.ts

@@ -0,0 +1,19 @@
+/**
+ * Contract for hashing services.
+ */
+export interface Hasher {
+  /**
+   * Hash a plain-text value.
+   */
+  make(value: string): Promise<string>
+
+  /**
+   * Check a plain-text value against a hash.
+   */
+  check(value: string, hashedValue: string): Promise<boolean>
+
+  /**
+   * Check if the given hash needs to be re-hashed (e.g. cost changed).
+   */
+  needsRehash(hashedValue: string): boolean
+}

package/src/contracts/Middleware.ts

@@ -0,0 +1,23 @@
+import type { MantiqRequest } from './Request.ts'
+
+export type NextFunction = () => Promise<Response>
+
+export interface Middleware {
+  /**
+   * Handle an incoming request.
+   * Call next() to pass to the next middleware or route handler.
+   * Return a Response without calling next() to short-circuit.
+   */
+  handle(request: MantiqRequest, next: NextFunction): Promise<Response>
+
+  /**
+   * Optional: runs after the response is sent to the client.
+   * Useful for logging, cleanup, analytics.
+   */
+  terminate?(request: MantiqRequest, response: Response): Promise<void>
+
+  /**
+   * Optional: set parameters parsed from the middleware alias string (e.g., 'throttle:60,1').
+   */
+  setParameters?(params: string[]): void
+}

package/src/contracts/Request.ts

@@ -0,0 +1,54 @@
+import type { UploadedFile } from '../http/UploadedFile.ts'
+import type { SessionStore } from '../session/Store.ts'
+
+export interface MantiqRequest {
+  // ── HTTP basics ──────────────────────────────────────────────────────────
+  method(): string
+  path(): string
+  url(): string
+  fullUrl(): string
+
+  // ── Input ────────────────────────────────────────────────────────────────
+  query(key: string, defaultValue?: string): string
+  query(): Record<string, string>
+  input(key: string, defaultValue?: any): Promise<any>
+  input(): Promise<Record<string, any>>
+  only(...keys: string[]): Promise<Record<string, any>>
+  except(...keys: string[]): Promise<Record<string, any>>
+  has(...keys: string[]): boolean
+  filled(...keys: string[]): Promise<boolean>
+
+  // ── Headers & metadata ───────────────────────────────────────────────────
+  header(key: string, defaultValue?: string): string | undefined
+  headers(): Record<string, string>
+  cookie(key: string, defaultValue?: string): string | undefined
+  setCookies(cookies: Record<string, string>): void
+  ip(): string
+  userAgent(): string
+  accepts(...types: string[]): string | false
+  expectsJson(): boolean
+  isJson(): boolean
+
+  // ── Files ────────────────────────────────────────────────────────────────
+  file(key: string): UploadedFile | null
+  files(key: string): UploadedFile[]
+  hasFile(key: string): boolean
+
+  // ── Route params ─────────────────────────────────────────────────────────
+  param(key: string, defaultValue?: any): any
+  params(): Record<string, any>
+  setRouteParams(params: Record<string, any>): void
+
+  // ── Session ──────────────────────────────────────────────────────────────
+  session(): SessionStore
+  setSession(session: SessionStore): void
+  hasSession(): boolean
+
+  // ── Auth ─────────────────────────────────────────────────────────────────
+  user<T = any>(): T | null
+  isAuthenticated(): boolean
+  setUser(user: any): void
+
+  // ── Raw ──────────────────────────────────────────────────────────────────
+  raw(): Request
+}

package/src/contracts/Response.ts

@@ -0,0 +1,19 @@
+export interface CookieOptions {
+  maxAge?: number
+  expires?: Date
+  path?: string
+  domain?: string
+  secure?: boolean
+  httpOnly?: boolean
+  sameSite?: 'Strict' | 'Lax' | 'None'
+}
+
+export interface MantiqResponseBuilder {
+  status(code: number): this
+  header(key: string, value: string): this
+  withHeaders(headers: Record<string, string>): this
+  cookie(name: string, value: string, options?: CookieOptions): this
+  json(data: any): Response
+  html(content: string): Response
+  redirect(url: string): Response
+}

package/src/contracts/Router.ts

@@ -0,0 +1,62 @@
+import type { Constructor } from './Container.ts'
+import type { MantiqRequest } from './Request.ts'
+
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS'
+
+export type RouteAction =
+  | [Constructor<any>, string]
+  | ((request: MantiqRequest) => any)
+  | string
+
+export interface RouteGroupOptions {
+  prefix?: string
+  middleware?: string[]
+  as?: string
+  namespace?: string
+}
+
+export interface RouteMatch {
+  action: RouteAction
+  params: Record<string, any>
+  middleware: string[]
+  routeName?: string
+}
+
+export interface RouteDefinition {
+  method: HttpMethod | HttpMethod[]
+  path: string
+  action: RouteAction
+  name?: string
+  middleware: string[]
+  wheres: Record<string, RegExp>
+}
+
+export interface Router {
+  get(path: string, action: RouteAction): RouterRoute
+  post(path: string, action: RouteAction): RouterRoute
+  put(path: string, action: RouteAction): RouterRoute
+  patch(path: string, action: RouteAction): RouterRoute
+  delete(path: string, action: RouteAction): RouterRoute
+  options(path: string, action: RouteAction): RouterRoute
+  match(methods: HttpMethod[], path: string, action: RouteAction): RouterRoute
+  any(path: string, action: RouteAction): RouterRoute
+  resource(name: string, controller: Constructor<any>): void
+  apiResource(name: string, controller: Constructor<any>): void
+  group(options: RouteGroupOptions, callback: (router: Router) => void): void
+  url(name: string, params?: Record<string, any>, absolute?: boolean): string
+  resolve(request: MantiqRequest): RouteMatch
+  routes(): RouteDefinition[]
+  model(param: string, model: Constructor<any>): void
+  bind(param: string, resolver: (value: string) => Promise<any>): void
+  /** Register controller classes for string-based resolution ('AuthController@login') */
+  controllers(map: Record<string, Constructor<any>>): void
+}
+
+export interface RouterRoute {
+  name(name: string): this
+  middleware(...middleware: string[]): this
+  where(param: string, pattern: string | RegExp): this
+  whereNumber(param: string): this
+  whereAlpha(param: string): this
+  whereUuid(param: string): this
+}

package/src/contracts/ServiceProvider.ts

@@ -0,0 +1,31 @@
+import type { Bindable, Container } from './Container.ts'
+
+export abstract class ServiceProvider {
+  constructor(protected app: Container) {}
+
+  /**
+   * Register bindings in the container.
+   * Called for ALL providers before any boot() methods are called.
+   * Do NOT resolve dependencies here — other providers may not be registered yet.
+   */
+  register(): void | Promise<void> {}
+
+  /**
+   * Boot the service. Called after all providers are registered.
+   * Safe to resolve dependencies from the container.
+   */
+  boot(): void | Promise<void> {}
+
+  /**
+   * If true, this provider is lazy-loaded.
+   * It is registered but not booted until one of its bindings is first resolved.
+   */
+  deferred: boolean = false
+
+  /**
+   * The bindings this provider offers (used for deferred loading).
+   */
+  provides(): Bindable<any>[] {
+    return []
+  }
+}