@soederpop/luca 0.0.2

package/src/endpoint.ts

@@ -0,0 +1,340 @@
+import { Helper } from './helper.js'
+import type { Container, ContainerContext } from './container.js'
+import { Registry } from './registry.js'
+import { z } from 'zod'
+import { EndpointStateSchema, EndpointOptionsSchema, EndpointEventsSchema } from './schemas/base.js'
+
+export interface AvailableEndpoints {}
+
+export type EndpointState = z.infer<typeof EndpointStateSchema>
+export type EndpointOptions = z.infer<typeof EndpointOptionsSchema>
+
+export type EndpointHandler = (
+  parameters: Record<string, any>,
+  context: EndpointContext
+) => Promise<any> | any
+
+export type EndpointContext = {
+  container: Container<any>
+  request: any
+  response: any
+  query: Record<string, any>
+  body: Record<string, any>
+  params: Record<string, any>
+}
+
+export interface EndpointRateLimit {
+  /** Maximum requests allowed per window */
+  maxRequests: number
+  /** Window size in seconds (default: 1) */
+  windowSeconds?: number
+}
+
+export interface EndpointModule {
+  path: string
+  get?: EndpointHandler
+  post?: EndpointHandler
+  put?: EndpointHandler
+  patch?: EndpointHandler
+  delete?: EndpointHandler
+  getSchema?: z.ZodType
+  postSchema?: z.ZodType
+  putSchema?: z.ZodType
+  patchSchema?: z.ZodType
+  deleteSchema?: z.ZodType
+  /** Rate limit applied to all methods on this endpoint */
+  rateLimit?: EndpointRateLimit
+  /** Per-method rate limits (overrides the endpoint-level rateLimit) */
+  getRateLimit?: EndpointRateLimit
+  postRateLimit?: EndpointRateLimit
+  putRateLimit?: EndpointRateLimit
+  patchRateLimit?: EndpointRateLimit
+  deleteRateLimit?: EndpointRateLimit
+  description?: string
+  tags?: string[]
+}
+
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete'] as const
+
+/**
+ * Sliding-window rate limiter keyed by IP address.
+ * Tracks timestamps of requests and prunes entries older than the window.
+ */
+class RateLimiter {
+  private _windows = new Map<string, number[]>()
+
+  /** Returns true if the request is allowed, false if rate-limited. */
+  allow(key: string, maxRequests: number, windowMs: number): boolean {
+    const now = Date.now()
+    let timestamps = this._windows.get(key)
+
+    if (!timestamps) {
+      timestamps = []
+      this._windows.set(key, timestamps)
+    }
+
+    // Prune timestamps outside the window
+    while (timestamps.length > 0 && timestamps[0] <= now - windowMs) {
+      timestamps.shift()
+    }
+
+    if (timestamps.length >= maxRequests) {
+      return false
+    }
+
+    timestamps.push(now)
+    return true
+  }
+
+  /** Clear all tracking state */
+  reset(): void {
+    this._windows.clear()
+  }
+}
+
+export type EndpointFactory = <T extends keyof AvailableEndpoints>(
+  key: T,
+  options?: ConstructorParameters<AvailableEndpoints[T]>[0]
+) => NonNullable<InstanceType<AvailableEndpoints[T]>>
+
+export interface EndpointsInterface {
+  endpoints: EndpointsRegistry
+  endpoint: EndpointFactory
+}
+
+export class Endpoint<
+  T extends EndpointState = EndpointState,
+  K extends EndpointOptions = EndpointOptions
+> extends Helper<T, K> {
+  static override shortcut = 'endpoints.base'
+  static override description = 'File-based HTTP endpoint with Remix-like DX'
+  static override stateSchema = EndpointStateSchema
+  static override optionsSchema = EndpointOptionsSchema
+  static override eventsSchema = EndpointEventsSchema
+
+  private _module: EndpointModule | null = null
+  private _rateLimiter = new RateLimiter()
+
+  static attach(container: Container & EndpointsInterface): any {
+    Object.assign(container, {
+      get endpoints() {
+        return endpoints
+      },
+
+      endpoint<T extends keyof AvailableEndpoints>(
+        id: T,
+        options?: ConstructorParameters<AvailableEndpoints[T]>[0]
+      ): InstanceType<AvailableEndpoints[T]> {
+        const BaseClass = endpoints.lookup(id as string) as any
+
+        return container.createHelperInstance({
+          cache: helperCache,
+          type: 'endpoint',
+          id: String(id),
+          BaseClass,
+          options,
+          fallbackName: String(id),
+        }) as InstanceType<AvailableEndpoints[T]>
+      },
+    })
+
+    container.registerHelperType('endpoints', 'endpoint')
+
+    return container
+  }
+
+  override get initialState(): T {
+    return ({
+      mounted: false,
+      path: this.options.path || '',
+      methods: [],
+      requestCount: 0,
+    } as unknown) as T
+  }
+
+  get path() {
+    return this.options.path
+  }
+
+  get module() {
+    return this._module
+  }
+
+  get methods(): string[] {
+    if (!this._module) return []
+    return HTTP_METHODS.filter((m) => typeof (this._module as any)[m] === 'function')
+  }
+
+  get isMounted() {
+    return !!this.state.get('mounted')
+  }
+
+  async load(mod?: EndpointModule): Promise<this> {
+    if (mod) {
+      this._module = mod
+    } else if (this.options.filePath) {
+      const imported = await import(`${this.options.filePath}?t=${Date.now()}`)
+      this._module = imported.default || imported
+    }
+
+    this.state.set('methods', this.methods)
+    this.state.set('path', this.path)
+    this.emit('loaded', this._module)
+    return this
+  }
+
+  async reload(): Promise<this> {
+    this._module = null
+    return this.load()
+  }
+
+  handler(method: string): EndpointHandler | undefined {
+    return this._module?.[method as keyof EndpointModule] as EndpointHandler | undefined
+  }
+
+  schema(method: string): z.ZodType | undefined {
+    return this._module?.[`${method}Schema` as keyof EndpointModule] as z.ZodType | undefined
+  }
+
+  /** Returns the rate limit config for a given method, or undefined if none. */
+  rateLimitFor(method: string): EndpointRateLimit | undefined {
+    const perMethod = this._module?.[`${method}RateLimit` as keyof EndpointModule] as EndpointRateLimit | undefined
+    return perMethod || this._module?.rateLimit
+  }
+
+  /** Access the rate limiter instance (useful for testing or manual resets) */
+  get rateLimiter(): RateLimiter {
+    return this._rateLimiter
+  }
+
+  mount(app: any): this {
+    for (const method of this.methods) {
+      const endpoint = this
+
+      app[method](this.path, async (req: any, res: any) => {
+        try {
+          // Rate limit check
+          const limit = endpoint.rateLimitFor(method)
+          if (limit) {
+            const ip = req.ip || req.socket?.remoteAddress || 'unknown'
+            const key = `${method}:${ip}`
+            const windowMs = (limit.windowSeconds ?? 1) * 1000
+            if (!endpoint._rateLimiter.allow(key, limit.maxRequests, windowMs)) {
+              endpoint.emit('error', new Error(`Rate limit exceeded for ${method.toUpperCase()} ${endpoint.path}`))
+              res.status(429).json({ error: 'Too Many Requests' })
+              return
+            }
+          }
+
+          const currentHandler = endpoint.handler(method)
+          if (!currentHandler) {
+            res.status(404).json({ error: 'Not found' })
+            return
+          }
+
+          const parameters = { ...req.query, ...req.body, ...req.params }
+          const currentSchema = endpoint.schema(method)
+          const validated = currentSchema ? currentSchema.parse(parameters) : parameters
+
+          const ctx: EndpointContext = {
+            container: endpoint.container,
+            request: req,
+            response: res,
+            query: req.query || {},
+            body: req.body || {},
+            params: req.params || {},
+          }
+
+          const result = await currentHandler(validated, ctx)
+          endpoint.state.set('requestCount', (endpoint.state.get('requestCount') || 0) + 1)
+          endpoint.emit('request', method, endpoint.path, parameters)
+
+          if (!res.headersSent) {
+            res.json(result)
+          }
+        } catch (err: any) {
+          endpoint.emit('error', err)
+          if (!res.headersSent) {
+            if (err.name === 'ZodError') {
+              const issues = err.issues || err.errors || []
+              const details = issues.map((e: any) => `${(e.path || []).join('.')}: ${e.message}`).join(', ')
+              console.error(`[${method.toUpperCase()} ${endpoint.path}] Validation failed: ${details}`)
+              res.status(400).json({ error: `Validation failed: ${details}`, details: issues })
+            } else {
+              console.error(`[${method.toUpperCase()} ${endpoint.path}] ${err.message}`)
+              res.status(500).json({ error: err.message })
+            }
+          }
+        }
+      })
+    }
+
+    this.state.set('mounted', true)
+    this.emit('mounted', this.path)
+    return this
+  }
+
+  toOpenAPIPathItem(): Record<string, any> {
+    const pathItem: Record<string, any> = {}
+
+    for (const method of this.methods) {
+      const methodSchema = this.schema(method)
+      const operationId = `${method}_${this.path.replace(/\//g, '_').replace(/^_/, '')}`
+
+      const operation: Record<string, any> = {
+        operationId,
+        summary: this._module?.description || `${method.toUpperCase()} ${this.path}`,
+        tags: this._module?.tags || [],
+        responses: {
+          '200': {
+            description: 'Successful response',
+            content: { 'application/json': { schema: { type: 'object' } } },
+          },
+          ...(this.rateLimitFor(method) ? { '429': { description: 'Rate limit exceeded' } } : {}),
+          '400': { description: 'Validation error' },
+          '500': { description: 'Server error' },
+        },
+      }
+
+      if (methodSchema) {
+        try {
+          const jsonSchema = (methodSchema as any).toJSONSchema()
+
+          if (method === 'get' || method === 'delete') {
+            operation.parameters = Object.entries((jsonSchema as any).properties || {}).map(
+              ([name, prop]: [string, any]) => ({
+                name,
+                in: 'query',
+                required: (jsonSchema as any).required?.includes(name) || false,
+                schema: prop,
+                description: prop.description || '',
+              })
+            )
+          } else {
+            operation.requestBody = {
+              required: true,
+              content: { 'application/json': { schema: jsonSchema } },
+            }
+          }
+        } catch {
+          // Schema conversion failed, serve without parameter docs
+        }
+      }
+
+      pathItem[method] = operation
+    }
+
+    return pathItem
+  }
+}
+
+export class EndpointsRegistry extends Registry<Endpoint<any>> {
+  override scope = 'endpoints'
+  override baseClass = Endpoint
+}
+
+export const endpoints = new EndpointsRegistry()
+
+export const helperCache = new Map()
+
+export default Endpoint

package/src/feature.ts

@@ -0,0 +1,75 @@
+import { Helper } from './helper.js';
+import { Registry } from './registry.js'
+import type { ContainerContext } from './container.js'
+import { kebabCase, camelCase } from 'lodash-es'
+import type { YAML } from './node/features/yaml.js';
+import { z } from 'zod'
+import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from './schemas/base.js'
+
+/**
+ * Use module augmentation to register features, the same way you would register
+ * them at runtime.  This will help developers get autocomplete etc.
+*/
+export interface AvailableFeatures {
+    yaml: typeof YAML
+}
+
+export type FeatureOptions = z.infer<typeof FeatureOptionsSchema>
+export type FeatureState = z.infer<typeof FeatureStateSchema>
+
+export abstract class Feature<T extends FeatureState = FeatureState, K extends FeatureOptions = FeatureOptions> extends Helper<T, K> {
+    static override stateSchema = FeatureStateSchema
+    static override optionsSchema = FeatureOptionsSchema
+    static override eventsSchema = FeatureEventsSchema
+
+    get shortcut() {
+        return (this.constructor as any).shortcut as string
+    }
+
+    get isEnabled() {
+        return this.state.get('enabled')
+    }    
+   
+    constructor(options: K, context: ContainerContext) {
+        super(options, context)
+
+        if(typeof context.container !== 'object') {
+            console.error(this, options, context)
+            throw new Error('You should not instantiate a feature directly. Use container.feature() instead.')
+        }
+
+
+        if(options?.enable) {
+          this.enable()
+        }
+    }
+
+    /** 
+     * For features where there only needs to be a single instance, you
+     * can use this method to attach the feature to the container.
+    */
+    protected attachToContainer() {
+        Object.defineProperty(this.container, this.shortcut.split('.').pop()!, {
+            get: () => this,
+            configurable: true,
+            enumerable: true,
+        })        
+    }
+
+    async enable(options: any = {}) : Promise<this> {
+        this.attachToContainer()
+        this.emit('enabled')
+        this.state.set('enabled', true)
+        
+        this.container.emit('featureEnabled', this.shortcut, this)
+
+        return this
+    }
+}
+
+export class FeaturesRegistry extends Registry<Feature<any, any>> { 
+    override scope = "features"
+    override baseClass = Feature as any
+}
+
+export const features = new FeaturesRegistry()

package/src/hash-object.ts

@@ -0,0 +1,97 @@
+/**
+ * Browser-compatible object hashing. Produces a deterministic string signature
+ * for any JavaScript value, suitable for use as a cache key or identity check.
+ *
+ * Replaces the `object-hash` npm package which has Node.js-specific dependencies.
+ */
+
+function sortedEntries(obj: Record<string, any>): [string, any][] {
+  return Object.keys(obj).sort().map((k) => [k, obj[k]])
+}
+
+function serialize(value: any, seen: Set<any>): string {
+  if (value === null) return 'null'
+  if (value === undefined) return 'undefined'
+
+  const type = typeof value
+
+  if (type === 'boolean' || type === 'number' || type === 'bigint') {
+    return `${type}:${value}`
+  }
+
+  if (type === 'string') {
+    return `string:${value.length}:${value}`
+  }
+
+  if (type === 'symbol') {
+    return `symbol:${value.toString()}`
+  }
+
+  if (type === 'function') {
+    return `function:${value.name || 'anonymous'}`
+  }
+
+  // Circular reference guard
+  if (seen.has(value)) return 'circular'
+  seen.add(value)
+
+  if (value instanceof Date) {
+    return `date:${value.toISOString()}`
+  }
+
+  if (value instanceof RegExp) {
+    return `regexp:${value.toString()}`
+  }
+
+  if (value instanceof Error) {
+    return `error:${value.name}:${value.message}`
+  }
+
+  if (value instanceof Set) {
+    const items = Array.from(value).map((v) => serialize(v, seen)).sort()
+    return `set:[${items.join(',')}]`
+  }
+
+  if (value instanceof Map) {
+    const entries = Array.from(value.entries())
+      .map(([k, v]) => `${serialize(k, seen)}=>${serialize(v, seen)}`)
+      .sort()
+    return `map:{${entries.join(',')}}`
+  }
+
+  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+    const buf = value instanceof ArrayBuffer ? new Uint8Array(value) : new Uint8Array((value as any).buffer, (value as any).byteOffset, (value as any).byteLength)
+    return `buffer:${Array.from(buf).join(',')}`
+  }
+
+  if (Array.isArray(value)) {
+    const items = value.map((v) => serialize(v, seen))
+    return `array:[${items.join(',')}]`
+  }
+
+  // Plain objects — sort keys for determinism
+  if (type === 'object') {
+    const entries = sortedEntries(value)
+      .map(([k, v]) => `${k}:${serialize(v, seen)}`)
+    return `object:{${entries.join(',')}}`
+  }
+
+  return `unknown:${String(value)}`
+}
+
+/**
+ * Simple non-crypto hash (djb2 variant) that works in all JS environments.
+ */
+function djb2(str: string): string {
+  let h1 = 0x811c9dc5 // FNV offset basis
+  for (let i = 0; i < str.length; i++) {
+    h1 ^= str.charCodeAt(i)
+    h1 = (h1 * 0x01000193) >>> 0 // FNV prime, keep as uint32
+  }
+  return h1.toString(36)
+}
+
+export default function hashObject(value: any): string {
+  const serialized = serialize(value, new Set())
+  return djb2(serialized)
+}