@db3.ai/app 0.1.0-beta.1

package/dist/auth/providers/resolveAuthProviders.js

@@ -0,0 +1,111 @@
+import { PASSWORD_AUTH_PROVIDER } from '../AuthProvider.js';
+import { GOOGLE_AUTH_PROVIDER, GoogleAuthProvider } from './GoogleAuthProvider.js';
+import { PasswordAuthProvider } from './PasswordAuthProvider.js';
+/**
+ * Builds provider driver instances from app auth provider config.
+ *
+ * @param providers - Provider registry from explicit auth options or app config.
+ * @param options - Construction dependencies shared by provider instances.
+ * @returns Enabled provider driver instances keyed by provider name.
+ */
+export function resolveAuthProviders(providers, options) {
+    const registry = {};
+    for (const [provider, config] of Object.entries(providers)) {
+        const driver = resolveAuthProvider(provider, config, options);
+        if (driver) {
+            registry[provider] = driver;
+        }
+    }
+    return registry;
+}
+/**
+ * Builds one provider driver from its config entry.
+ *
+ * @param provider - Provider registry key.
+ * @param config - Provider config entry.
+ * @param factoryOptions - Construction dependencies shared by provider instances.
+ * @returns Provider driver, or null when disabled.
+ */
+function resolveAuthProvider(provider, config, factoryOptions) {
+    if (config === false)
+        return null;
+    if (isAuthProviderDriver(config))
+        return config;
+    const options = config === true
+        ? {}
+        : config;
+    if (options.enabled === false)
+        return null;
+    const driver = typeof options.driver === 'string'
+        ? options.driver
+        : provider;
+    switch (driver) {
+        case PASSWORD_AUTH_PROVIDER:
+            return new PasswordAuthProvider({
+                identityModel: factoryOptions.identityModel,
+                providerModel: factoryOptions.providerModel,
+                passwordHash: factoryOptions.passwordHash,
+            });
+        case GOOGLE_AUTH_PROVIDER:
+            return new GoogleAuthProvider(googleOptionsFromConfig(options));
+        default:
+            throw new Error(`Unknown auth provider driver "${driver}".`);
+    }
+}
+/**
+ * Checks whether a config entry is already a provider driver.
+ *
+ * @param value - Config value to inspect.
+ * @returns True when the value satisfies the provider driver contract.
+ */
+function isAuthProviderDriver(value) {
+    return typeof value === 'object'
+        && value !== null
+        && typeof value.provider === 'string'
+        && typeof value.verify === 'function';
+}
+/**
+ * Converts generic config values into Google provider options.
+ *
+ * @param options - Generic provider config object.
+ * @returns Google provider options.
+ */
+function googleOptionsFromConfig(options) {
+    const { driver: _driver, enabled: _enabled, clientId, clientIds, hostedDomain, ...rest } = options;
+    return {
+        ...rest,
+        clientId: stringOption(clientId),
+        clientIds: stringArrayOption(clientIds),
+        hostedDomain: stringOption(hostedDomain),
+    };
+}
+/**
+ * Reads an optional string config value.
+ *
+ * @param value - Unknown config value.
+ * @returns String value, or undefined.
+ */
+function stringOption(value) {
+    return typeof value === 'string' && value.trim()
+        ? value.trim()
+        : undefined;
+}
+/**
+ * Reads an optional string array config value.
+ *
+ * @param value - Unknown config value.
+ * @returns String array value.
+ */
+function stringArrayOption(value) {
+    if (typeof value === 'string') {
+        return value
+            .split(',')
+            .map(item => item.trim())
+            .filter(Boolean);
+    }
+    if (!Array.isArray(value))
+        return undefined;
+    return value
+        .map(item => stringOption(item))
+        .filter((item) => Boolean(item));
+}

package/dist/cache/Cache.d.ts

@@ -0,0 +1,67 @@
+import type * as cache from './contracts/index.js';
+/**
+ * Application cache service exposed through `app().cache`.
+ *
+ * The framework owns cache naming and lifecycle while Cache Manager currently
+ * supplies storage behavior through memory and Redis Keyv adapters.
+ *
+ * @example
+     * const summary = await app().cache.getOrSet(`notes:v1:${ownerId}:summary`, async () => {
+     * 	return { count: await Note.where('owner', ownerId).count() };
+ * }, {
+ * 	ttl: 60_000,
+ * });
+ */
+export declare class Cache implements cache.CacheDriver {
+    #private;
+    /**
+     * Creates the configured cache service.
+     *
+     * @param options - Named cache-store configuration.
+     * @param driver - Optional concrete driver used by focused tests or providers.
+     */
+    constructor(options?: cache.CacheOptions, driver?: cache.CacheDriver);
+    /**
+     * Retrieves a cached value.
+     *
+     * @param key - Stable application cache key.
+     * @returns Cached value or undefined after a miss.
+     */
+    get<TValue>(key: string): Promise<TValue | undefined>;
+    /**
+     * Stores one defined cache value.
+     *
+     * @param key - Stable application cache key.
+     * @param value - Defined value to retain.
+     * @param options - Optional per-write TTL.
+     * @returns The stored value.
+     */
+    set<TValue>(key: string, value: TValue, options?: cache.CacheSetOptions): Promise<TValue>;
+    /**
+     * Returns a cached value or computes and stores it after a miss.
+     *
+     * Cache Manager coalesces concurrent misses for the same key within this
+     * process, so the factory runs once while other callers await its result.
+     *
+     * @param key - Stable application cache key.
+     * @param factory - Value producer invoked after a cache miss.
+     * @param options - TTL and optional background-refresh controls.
+     * @returns Cached or newly resolved value.
+     */
+    getOrSet<TValue>(key: string, factory: cache.CacheValueFactory<TValue>, options?: cache.CacheGetOrSetOptions<TValue>): Promise<TValue>;
+    /**
+     * Removes one cache key.
+     *
+     * @param key - Cache key to remove.
+     * @returns True when the driver accepted the deletion.
+     */
+    forget(key: string): Promise<boolean>;
+    /**
+     * Removes every key owned by the configured store.
+     */
+    clear(): Promise<void>;
+    /**
+     * Releases resources held by the configured cache driver.
+     */
+    close(): Promise<void>;
+}

package/dist/cache/Cache.js

@@ -0,0 +1,115 @@
+import { createCacheDriver } from './drivers/createCacheDriver.js';
+/**
+ * Application cache service exposed through `app().cache`.
+ *
+ * The framework owns cache naming and lifecycle while Cache Manager currently
+ * supplies storage behavior through memory and Redis Keyv adapters.
+ *
+ * @example
+     * const summary = await app().cache.getOrSet(`notes:v1:${ownerId}:summary`, async () => {
+     * 	return { count: await Note.where('owner', ownerId).count() };
+ * }, {
+ * 	ttl: 60_000,
+ * });
+ */
+export class Cache {
+    #driver;
+    #closePromise = null;
+    /**
+     * Creates the configured cache service.
+     *
+     * @param options - Named cache-store configuration.
+     * @param driver - Optional concrete driver used by focused tests or providers.
+     */
+    constructor(options = {}, driver) {
+        this.#driver = driver ?? createCacheDriver(options);
+    }
+    /**
+     * Retrieves a cached value.
+     *
+     * @param key - Stable application cache key.
+     * @returns Cached value or undefined after a miss.
+     */
+    async get(key) {
+        return this.#driver.get(cacheKey(key));
+    }
+    /**
+     * Stores one defined cache value.
+     *
+     * @param key - Stable application cache key.
+     * @param value - Defined value to retain.
+     * @param options - Optional per-write TTL.
+     * @returns The stored value.
+     */
+    async set(key, value, options = {}) {
+        return this.#driver.set(cacheKey(key), definedCacheValue(value, key), options);
+    }
+    /**
+     * Returns a cached value or computes and stores it after a miss.
+     *
+     * Cache Manager coalesces concurrent misses for the same key within this
+     * process, so the factory runs once while other callers await its result.
+     *
+     * @param key - Stable application cache key.
+     * @param factory - Value producer invoked after a cache miss.
+     * @param options - TTL and optional background-refresh controls.
+     * @returns Cached or newly resolved value.
+     */
+    async getOrSet(key, factory, options = {}) {
+        const normalizedKey = cacheKey(key);
+        return this.#driver.getOrSet(normalizedKey, async () => {
+            const value = await factory();
+            return definedCacheValue(value, normalizedKey);
+        }, options);
+    }
+    /**
+     * Removes one cache key.
+     *
+     * @param key - Cache key to remove.
+     * @returns True when the driver accepted the deletion.
+     */
+    async forget(key) {
+        return this.#driver.forget(cacheKey(key));
+    }
+    /**
+     * Removes every key owned by the configured store.
+     */
+    async clear() {
+        await this.#driver.clear();
+    }
+    /**
+     * Releases resources held by the configured cache driver.
+     */
+    async close() {
+        this.#closePromise ??= this.#driver.close();
+        await this.#closePromise;
+    }
+}
+/**
+ * Validates and normalizes an application cache key.
+ *
+ * @param key - Candidate cache key.
+ * @returns Trimmed non-empty cache key.
+ */
+function cacheKey(key) {
+    const normalized = key.trim();
+    if (!normalized) {
+        throw new Error('Cache keys must be non-empty strings.');
+    }
+    return normalized;
+}
+/**
+ * Rejects undefined because it represents a cache miss in Cache Manager.
+ *
+ * Null, false, zero, and empty strings remain valid cached values.
+ *
+ * @param value - Candidate cache value.
+ * @param key - Cache key used in the validation error.
+ * @returns Defined cache value.
+ */
+function definedCacheValue(value, key) {
+    if (value === undefined) {
+        throw new TypeError(`Cache value for "${key}" cannot be undefined because undefined represents a cache miss.`);
+    }
+    return value;
+}

package/dist/cache/contracts/CacheDriver.d.ts

@@ -0,0 +1,10 @@
+import type { CacheRepository } from './CacheRepository.js';
+/**
+ * Cache backend boundary owned by the framework cache service.
+ */
+export interface CacheDriver extends CacheRepository {
+    /**
+     * Releases connections and other resources held by the cache backend.
+     */
+    close(): Promise<void>;
+}

package/dist/cache/contracts/CacheDriver.js

@@ -0,0 +1 @@
+export {};

package/dist/cache/contracts/CacheOperations.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Per-write cache options.
+ */
+export interface CacheSetOptions {
+    /** Time-to-live in milliseconds, overriding the configured store default. */
+    ttl?: number;
+}
+/**
+ * Options controlling one cache-through lookup.
+ */
+export interface CacheGetOrSetOptions<TValue> {
+    /**
+     * Time-to-live in milliseconds or a function deriving it from the resolved value.
+     */
+    ttl?: number | ((value: TValue) => number);
+    /**
+     * Remaining TTL threshold that triggers a background refresh.
+     *
+     * The stale value is returned while the factory refreshes it.
+     */
+    refreshThreshold?: number | ((value: TValue) => number);
+}
+/**
+ * Factory that computes a value after a cache miss.
+ */
+export type CacheValueFactory<TValue> = () => TValue | Promise<TValue>;

package/dist/cache/contracts/CacheOperations.js

@@ -0,0 +1 @@
+export {};

package/dist/cache/contracts/CacheOptions.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Bounded in-process cache store configuration.
+ */
+export interface MemoryCacheStoreOptions {
+    /** Cache driver selected for this named store. */
+    driver: 'memory';
+    /** Default time-to-live in milliseconds. Omit for no default expiry. */
+    ttl?: number;
+    /** Maximum entries retained by the least-recently-used cache. Defaults to 1,000. */
+    maxEntries?: number;
+    /** Whether values are cloned when stored and retrieved. Defaults to true. */
+    clone?: boolean;
+}
+/**
+ * Redis cache store configuration using the official Keyv adapter.
+ */
+export interface RedisCacheStoreOptions {
+    /** Cache driver selected for this named store. */
+    driver: 'redis';
+    /** Redis connection URL including credentials and database when required. */
+    url: string;
+    /**
+     * Prefix isolating application cache keys from other Redis data.
+     *
+     * A namespace is required so clearing the cache cannot affect unrelated keys.
+     */
+    namespace: string;
+    /** Default time-to-live in milliseconds. Omit for no default expiry. */
+    ttl?: number;
+    /** Milliseconds allowed for the initial Redis connection attempt. */
+    connectionTimeoutMs?: number;
+    /** Number of namespaced keys removed in each cache-clear batch. */
+    clearBatchSize?: number;
+    /** Whether Redis connection failures should reject cache operations. */
+    throwOnConnectError?: boolean;
+    /** Whether Redis command errors should reject cache operations. */
+    throwOnErrors?: boolean;
+}
+/**
+ * Supported framework cache store configurations.
+ */
+export type CacheStoreOptions = MemoryCacheStoreOptions | RedisCacheStoreOptions;
+/**
+ * Named cache-store configuration resolved from the application config.
+ */
+export interface CacheOptions {
+    /** Named store used by `app().cache`. Defaults to `memory`. */
+    default?: string;
+    /** Cache stores available to the application. */
+    stores?: Record<string, CacheStoreOptions>;
+}

package/dist/cache/contracts/CacheOptions.js

@@ -0,0 +1 @@
+export {};

package/dist/cache/contracts/CacheRepository.d.ts

@@ -0,0 +1,45 @@
+import type { CacheGetOrSetOptions, CacheSetOptions, CacheValueFactory } from './CacheOperations.js';
+/**
+ * Application-facing cache operations shared by framework and app code.
+ */
+export interface CacheRepository {
+    /**
+     * Retrieves a cached value.
+     *
+     * @param key - Stable application cache key.
+     * @returns Cached value or undefined when the key is absent or expired.
+     */
+    get<TValue>(key: string): Promise<TValue | undefined>;
+    /**
+     * Stores one defined cache value.
+     *
+     * @param key - Stable application cache key.
+     * @param value - Defined value to retain.
+     * @param options - Optional per-write TTL.
+     * @returns The stored value.
+     */
+    set<TValue>(key: string, value: TValue, options?: CacheSetOptions): Promise<TValue>;
+    /**
+     * Returns a cached value or computes and stores it after a miss.
+     *
+     * Concurrent lookups for the same key share one in-flight factory execution
+     * within the current process.
+     *
+     * @param key - Stable application cache key.
+     * @param factory - Value producer invoked after a cache miss.
+     * @param options - TTL and optional background-refresh controls.
+     * @returns Cached or newly resolved value.
+     */
+    getOrSet<TValue>(key: string, factory: CacheValueFactory<TValue>, options?: CacheGetOrSetOptions<TValue>): Promise<TValue>;
+    /**
+     * Removes one cache key.
+     *
+     * @param key - Cache key to remove.
+     * @returns True when the underlying cache accepted the deletion.
+     */
+    forget(key: string): Promise<boolean>;
+    /**
+     * Removes every key owned by the configured cache store.
+     */
+    clear(): Promise<void>;
+}

package/dist/cache/contracts/CacheRepository.js

@@ -0,0 +1 @@
+export {};

package/dist/cache/contracts/index.d.ts

@@ -0,0 +1,4 @@
+export * from './CacheDriver.js';
+export * from './CacheOperations.js';
+export * from './CacheOptions.js';
+export * from './CacheRepository.js';

package/dist/cache/contracts/index.js

@@ -0,0 +1,4 @@
+export * from './CacheDriver.js';
+export * from './CacheOperations.js';
+export * from './CacheOptions.js';
+export * from './CacheRepository.js';

package/dist/cache/drivers/CacheManagerDriver.d.ts

@@ -0,0 +1,55 @@
+import type { Cache as ManagedCache } from 'cache-manager';
+import type * as cache from '../contracts/index.js';
+/**
+ * Cache driver backed by the Cache Manager package.
+ */
+export declare class CacheManagerDriver implements cache.CacheDriver {
+    #private;
+    private readonly manager;
+    /**
+     * Creates a driver around one configured Cache Manager instance.
+     *
+     * @param manager - Cache Manager instance containing the selected Keyv store.
+     */
+    constructor(manager: ManagedCache);
+    /**
+     * Retrieves a cached value from Cache Manager.
+     *
+     * @param key - Stable application cache key.
+     * @returns Cached value or undefined after a miss.
+     */
+    get<TValue>(key: string): Promise<TValue | undefined>;
+    /**
+     * Stores one value through Cache Manager.
+     *
+     * @param key - Stable application cache key.
+     * @param value - Value to retain.
+     * @param options - Optional per-write TTL.
+     * @returns The stored value.
+     */
+    set<TValue>(key: string, value: TValue, options?: cache.CacheSetOptions): Promise<TValue>;
+    /**
+     * Uses Cache Manager's coalesced wrapper for one cache-through lookup.
+     *
+     * @param key - Stable application cache key.
+     * @param factory - Value producer invoked after a miss.
+     * @param options - TTL and background-refresh controls.
+     * @returns Cached or newly resolved value.
+     */
+    getOrSet<TValue>(key: string, factory: cache.CacheValueFactory<TValue>, options?: cache.CacheGetOrSetOptions<TValue>): Promise<TValue>;
+    /**
+     * Deletes one cache key through Cache Manager.
+     *
+     * @param key - Cache key to remove.
+     * @returns True when Cache Manager accepted the deletion.
+     */
+    forget(key: string): Promise<boolean>;
+    /**
+     * Clears keys owned by the selected store.
+     */
+    clear(): Promise<void>;
+    /**
+     * Disconnects every Keyv store exactly once.
+     */
+    close(): Promise<void>;
+}

package/dist/cache/drivers/CacheManagerDriver.js

@@ -0,0 +1,68 @@
+/**
+ * Cache driver backed by the Cache Manager package.
+ */
+export class CacheManagerDriver {
+    manager;
+    #closePromise = null;
+    /**
+     * Creates a driver around one configured Cache Manager instance.
+     *
+     * @param manager - Cache Manager instance containing the selected Keyv store.
+     */
+    constructor(manager) {
+        this.manager = manager;
+    }
+    /**
+     * Retrieves a cached value from Cache Manager.
+     *
+     * @param key - Stable application cache key.
+     * @returns Cached value or undefined after a miss.
+     */
+    async get(key) {
+        return this.manager.get(key);
+    }
+    /**
+     * Stores one value through Cache Manager.
+     *
+     * @param key - Stable application cache key.
+     * @param value - Value to retain.
+     * @param options - Optional per-write TTL.
+     * @returns The stored value.
+     */
+    async set(key, value, options = {}) {
+        return this.manager.set(key, value, options.ttl);
+    }
+    /**
+     * Uses Cache Manager's coalesced wrapper for one cache-through lookup.
+     *
+     * @param key - Stable application cache key.
+     * @param factory - Value producer invoked after a miss.
+     * @param options - TTL and background-refresh controls.
+     * @returns Cached or newly resolved value.
+     */
+    async getOrSet(key, factory, options = {}) {
+        return this.manager.wrap(key, factory, options);
+    }
+    /**
+     * Deletes one cache key through Cache Manager.
+     *
+     * @param key - Cache key to remove.
+     * @returns True when Cache Manager accepted the deletion.
+     */
+    async forget(key) {
+        return this.manager.del(key);
+    }
+    /**
+     * Clears keys owned by the selected store.
+     */
+    async clear() {
+        await this.manager.clear();
+    }
+    /**
+     * Disconnects every Keyv store exactly once.
+     */
+    async close() {
+        this.#closePromise ??= this.manager.disconnect().then(() => { });
+        await this.#closePromise;
+    }
+}

package/dist/cache/drivers/createCacheDriver.d.ts

@@ -0,0 +1,8 @@
+import type * as cache from '../contracts/index.js';
+/**
+ * Creates the concrete cache driver selected by named application config.
+ *
+ * @param options - Named store configuration from `config.cache`.
+ * @returns Cache Manager driver using the selected memory or Redis store.
+ */
+export declare function createCacheDriver(options?: cache.CacheOptions): cache.CacheDriver;