@di-framework/cloudfoundry 5.2.3

package/dist/creators/relational.js

@@ -0,0 +1,179 @@
+const POSTGRES_PATTERNS = ['postgres', 'postgresql', 'elephantsql', 'crunchy'];
+const MYSQL_PATTERNS = ['mysql', 'cleardb', 'mariadb'];
+const SQLITE_PATTERNS = ['sqlite', 'sqlite3'];
+function matchesAny(str, patterns) {
+    const lower = str.toLowerCase();
+    return patterns.some((p) => lower.includes(p));
+}
+function detectDialectFromScheme(scheme) {
+    const s = scheme.toLowerCase().replace(':', '');
+    if (s === 'postgres' || s === 'postgresql')
+        return 'postgres';
+    if (s === 'mysql')
+        return 'mysql';
+    if (s === 'mariadb')
+        return 'mariadb';
+    if (s === 'sqlite' || s === 'sqlite3')
+        return 'sqlite';
+    return null;
+}
+export class RelationalServiceInfoCreator {
+    accept(serviceData) {
+        const label = serviceData.label || '';
+        const tags = (serviceData.tags || []).map((t) => String(t).toLowerCase());
+        const creds = (serviceData.credentials || {});
+        // 1. Label match
+        if (matchesAny(label, POSTGRES_PATTERNS) ||
+            matchesAny(label, MYSQL_PATTERNS) ||
+            matchesAny(label, SQLITE_PATTERNS)) {
+            return true;
+        }
+        // 2. Tag match
+        if (tags.some((t) => POSTGRES_PATTERNS.some((p) => t.includes(p)) ||
+            MYSQL_PATTERNS.some((p) => t.includes(p)) ||
+            SQLITE_PATTERNS.some((p) => t.includes(p)) ||
+            t === 'relational' ||
+            t === 'rdbms')) {
+            return true;
+        }
+        // 3. Credentials URI / JDBC / scheme inspection
+        const uriCandidate = String(creds.uri ?? creds.url ?? creds.jdbcUrl ?? '');
+        if (uriCandidate.startsWith('postgres://') || uriCandidate.startsWith('postgresql://')) {
+            return true;
+        }
+        if (uriCandidate.startsWith('mysql://') || uriCandidate.startsWith('mariadb://')) {
+            return true;
+        }
+        if (uriCandidate.startsWith('sqlite://') || uriCandidate.startsWith('sqlite:')) {
+            return true;
+        }
+        if (uriCandidate.startsWith('jdbc:postgresql:') || uriCandidate.startsWith('jdbc:mysql:')) {
+            return true;
+        }
+        return false;
+    }
+    createServiceInfo(serviceData) {
+        const creds = (serviceData.credentials || {});
+        const tags = (serviceData.tags || []).map(String);
+        const label = serviceData.label || '';
+        let rawUri = String(creds.uri ?? creds.url ?? '');
+        const jdbcUrlCandidate = creds.jdbcUrl ? String(creds.jdbcUrl) : undefined;
+        let dialect = 'postgres';
+        if (matchesAny(label, SQLITE_PATTERNS) || tags.some((t) => matchesAny(t, SQLITE_PATTERNS))) {
+            dialect = 'sqlite';
+        }
+        else if (matchesAny(label, MYSQL_PATTERNS) ||
+            tags.some((t) => matchesAny(t, MYSQL_PATTERNS))) {
+            dialect = matchesAny(label, ['mariadb']) || tags.includes('mariadb') ? 'mariadb' : 'mysql';
+        }
+        let host = String(creds.host ?? creds.hostname ?? 'localhost');
+        let port = typeof creds.port === 'number' ? creds.port : 5432;
+        if (typeof creds.port === 'string' && creds.port.trim().length > 0) {
+            const p = parseInt(creds.port, 10);
+            if (!Number.isNaN(p))
+                port = p;
+        }
+        let database = String(creationalDbName(creds));
+        let username = (creds.username ?? creds.user) ? String(creds.username ?? creds.user) : undefined;
+        let password = (creds.password ?? creds.pass) ? String(creds.password ?? creds.pass) : undefined;
+        let ssl = typeof creds.ssl === 'boolean' ? creds.ssl : undefined;
+        if (rawUri.startsWith('jdbc:')) {
+            // e.g. jdbc:postgresql://host:port/database
+            const normalized = rawUri.replace(/^jdbc:/, '');
+            try {
+                const parsed = new URL(normalized);
+                const schemeDialect = detectDialectFromScheme(parsed.protocol);
+                if (schemeDialect)
+                    dialect = schemeDialect;
+                if (parsed.hostname)
+                    host = parsed.hostname;
+                if (parsed.port)
+                    port = parseInt(parsed.port, 10);
+                if (parsed.pathname && parsed.pathname.length > 1) {
+                    database = decodeURIComponent(parsed.pathname.slice(1));
+                }
+                if (parsed.username)
+                    username = decodeURIComponent(parsed.username);
+                if (parsed.password)
+                    password = decodeURIComponent(parsed.password);
+                if (parsed.searchParams.has('ssl') || parsed.searchParams.has('sslmode')) {
+                    ssl =
+                        parsed.searchParams.get('ssl') === 'true' ||
+                            parsed.searchParams.get('sslmode') === 'require';
+                }
+            }
+            catch {
+                // preserve original
+            }
+        }
+        else if (rawUri.length > 0) {
+            try {
+                const parsed = new URL(rawUri);
+                const schemeDialect = detectDialectFromScheme(parsed.protocol);
+                if (schemeDialect)
+                    dialect = schemeDialect;
+                if (parsed.hostname)
+                    host = parsed.hostname;
+                if (parsed.port)
+                    port = parseInt(parsed.port, 10);
+                if (parsed.pathname && parsed.pathname.length > 1) {
+                    database = decodeURIComponent(parsed.pathname.slice(1));
+                }
+                if (parsed.username)
+                    username = decodeURIComponent(parsed.username);
+                if (parsed.password)
+                    password = decodeURIComponent(parsed.password);
+                if (parsed.searchParams.has('ssl') || parsed.searchParams.has('sslmode')) {
+                    ssl =
+                        parsed.searchParams.get('ssl') === 'true' ||
+                            parsed.searchParams.get('sslmode') === 'require';
+                }
+            }
+            catch {
+                // ignore url parse error
+            }
+        }
+        if (!rawUri || rawUri.startsWith('jdbc:')) {
+            const scheme = dialect === 'postgres' ? 'postgres' : dialect;
+            const auth = username ? (password ? `${username}:${password}@` : `${username}@`) : '';
+            rawUri = `${scheme}://${auth}${host}:${port}/${database}`;
+        }
+        const defaultPorts = {
+            postgres: 5432,
+            mysql: 3306,
+            mariadb: 3306,
+            sqlite: 0,
+        };
+        if (!port || (port === 5432 && dialect === 'mysql')) {
+            port = defaultPorts[dialect];
+        }
+        const jdbcUrl = jdbcUrlCandidate ??
+            `jdbc:${dialect === 'postgres' ? 'postgresql' : dialect}://${host}:${port}/${database}`;
+        return {
+            id: serviceData.name,
+            name: serviceData.name,
+            label: serviceData.label,
+            ...(serviceData.plan ? { plan: serviceData.plan } : {}),
+            tags,
+            credentials: Object.freeze({ ...creds }),
+            dialect,
+            host,
+            port,
+            database,
+            ...(username !== undefined ? { username } : {}),
+            ...(password !== undefined ? { password } : {}),
+            uri: rawUri,
+            jdbcUrl,
+            ...(ssl !== undefined ? { ssl } : {}),
+        };
+    }
+}
+function creationalDbName(creds) {
+    if (creds.database)
+        return String(creds.database);
+    if (creds.name)
+        return String(creds.name);
+    if (creds.db)
+        return String(creds.db);
+    return 'defaultdb';
+}

package/dist/creators/user-provided.d.ts

@@ -0,0 +1,6 @@
+import type { CloudFoundryServiceInfoCreator } from '../spi/creator.js';
+import type { RawVcapServiceData, UserProvidedServiceInfo } from '../types.js';
+export declare class UserProvidedServiceInfoCreator implements CloudFoundryServiceInfoCreator<UserProvidedServiceInfo> {
+    accept(serviceData: RawVcapServiceData): boolean;
+    createServiceInfo(serviceData: RawVcapServiceData): UserProvidedServiceInfo;
+}

package/dist/creators/user-provided.js

@@ -0,0 +1,36 @@
+export class UserProvidedServiceInfoCreator {
+    accept(serviceData) {
+        const label = (serviceData.label || '').toLowerCase();
+        return label === 'user-provided' || label.length === 0 || !label;
+    }
+    createServiceInfo(serviceData) {
+        const creds = (serviceData.credentials || {});
+        const tags = (serviceData.tags || []).map(String);
+        const uri = (creds.uri ?? creds.url) ? String(creds.uri ?? creds.url) : undefined;
+        const host = (creds.host ?? creds.hostname) ? String(creds.host ?? creds.hostname) : undefined;
+        let port;
+        if (typeof creds.port === 'number') {
+            port = creds.port;
+        }
+        else if (typeof creds.port === 'string' && creds.port.trim().length > 0) {
+            const p = parseInt(creds.port, 10);
+            if (!Number.isNaN(p))
+                port = p;
+        }
+        const username = (creds.username ?? creds.user) ? String(creds.username ?? creds.user) : undefined;
+        const password = (creds.password ?? creds.pass) ? String(creds.password ?? creds.pass) : undefined;
+        return {
+            id: serviceData.name,
+            name: serviceData.name,
+            label: serviceData.label || 'user-provided',
+            ...(serviceData.plan ? { plan: serviceData.plan } : {}),
+            tags,
+            credentials: Object.freeze({ ...creds }),
+            ...(uri !== undefined ? { uri } : {}),
+            ...(host !== undefined ? { host } : {}),
+            ...(port !== undefined ? { port } : {}),
+            ...(username !== undefined ? { username } : {}),
+            ...(password !== undefined ? { password } : {}),
+        };
+    }
+}

package/dist/decorators.d.ts

@@ -0,0 +1,34 @@
+import type { CloudFoundryServiceOptions, EnableCloudFoundryConnectorsOptions, ServiceFilter } from './types.js';
+/**
+ * Parameter or Property decorator that injects a bound Cloud Foundry service.
+ *
+ * @param serviceNameOrFilter Name, label, pattern, or filter object for the service.
+ * @param options Fallback environment keys, required flag, or default value.
+ *
+ * @example Property injection
+ * @Container()
+ * class DatabaseRepository {
+ *   @CloudFoundryService('my-postgres')
+ *   private dbService!: RelationalServiceInfo;
+ * }
+ *
+ * @example Constructor injection
+ * @Container()
+ * class CacheClient {
+ *   constructor(
+ *     @CloudFoundryService('my-redis') private redis: RedisServiceInfo
+ *   ) {}
+ * }
+ */
+export declare function CloudFoundryService(serviceNameOrFilter?: string | RegExp | ServiceFilter, options?: CloudFoundryServiceOptions): (targetClass: any, propertyKey?: string | symbol, parameterIndex?: number) => void;
+/**
+ * Injects Cloud Foundry application metadata (VCAP_APPLICATION).
+ */
+export declare function VcapApplication(options?: {
+    required?: boolean;
+    container?: unknown;
+}): (targetClass: any, propertyKey?: string | symbol, parameterIndex?: number) => void;
+/**
+ * Class decorator that enables Cloud Foundry connector auto-configuration on the DI container.
+ */
+export declare function EnableCloudFoundryConnectors(options?: EnableCloudFoundryConnectorsOptions): <T extends new (...args: any[]) => any>(ctor: T) => T;

package/dist/decorators.js

@@ -0,0 +1,202 @@
+import { defineMetadata, getOwnMetadata, useContainer } from '@di-framework/core/container';
+import { bindCloudFoundryConnectors, CF_APPLICATION_TOKEN } from './bindings.js';
+import { getDefaultEnvironment } from './environment.js';
+const INJECT_METADATA_KEY = 'di:inject';
+/**
+ * Parameter or Property decorator that injects a bound Cloud Foundry service.
+ *
+ * @param serviceNameOrFilter Name, label, pattern, or filter object for the service.
+ * @param options Fallback environment keys, required flag, or default value.
+ *
+ * @example Property injection
+ * @Container()
+ * class DatabaseRepository {
+ *   @CloudFoundryService('my-postgres')
+ *   private dbService!: RelationalServiceInfo;
+ * }
+ *
+ * @example Constructor injection
+ * @Container()
+ * class CacheClient {
+ *   constructor(
+ *     @CloudFoundryService('my-redis') private redis: RedisServiceInfo
+ *   ) {}
+ * }
+ */
+export function CloudFoundryService(serviceNameOrFilter, options = {}) {
+    return (
+    // biome-ignore lint/suspicious/noExplicitAny: decorator target
+    targetClass, propertyKey, parameterIndex) => {
+        const token = deriveServiceToken(serviceNameOrFilter);
+        // Property injection
+        if (propertyKey !== undefined && parameterIndex === undefined) {
+            const metadata = getOwnMetadata(INJECT_METADATA_KEY, targetClass) || {};
+            metadata[propertyKey] = token;
+            defineMetadata(INJECT_METADATA_KEY, metadata, targetClass);
+            if (targetClass.constructor && targetClass.constructor !== Object) {
+                const ctorMetadata = getOwnMetadata(INJECT_METADATA_KEY, targetClass.constructor) || {};
+                ctorMetadata[propertyKey] = token;
+                defineMetadata(INJECT_METADATA_KEY, ctorMetadata, targetClass.constructor);
+            }
+            // Define property getter fallback in case accessed without DI resolution
+            let cachedValue;
+            Object.defineProperty(targetClass, propertyKey, {
+                configurable: true,
+                enumerable: true,
+                get() {
+                    if (cachedValue !== undefined)
+                        return cachedValue;
+                    // Attempt container resolution first
+                    const container = options.container ?? useContainer();
+                    if (container && typeof container.resolve === 'function') {
+                        try {
+                            const res = container.resolve(token);
+                            if (res !== undefined && res !== null) {
+                                cachedValue = res;
+                                return cachedValue;
+                            }
+                        }
+                        catch {
+                            // fall through to environment lookup
+                        }
+                    }
+                    // Fallback to CloudFoundryEnvironment lookup
+                    const env = getDefaultEnvironment();
+                    let service = null;
+                    if (typeof serviceNameOrFilter === 'string') {
+                        service = env.getServiceInfo(serviceNameOrFilter);
+                    }
+                    else if (serviceNameOrFilter) {
+                        service = env.getServiceInfo(serviceNameOrFilter);
+                    }
+                    else {
+                        const all = env.getServiceInfos();
+                        service = all[0] ?? null;
+                    }
+                    if (service) {
+                        cachedValue = service;
+                        return cachedValue;
+                    }
+                    if (options.fallbackEnv) {
+                        const keys = Array.isArray(options.fallbackEnv)
+                            ? options.fallbackEnv
+                            : [options.fallbackEnv];
+                        for (const key of keys) {
+                            const val = process.env[key];
+                            if (val) {
+                                cachedValue = {
+                                    uri: val,
+                                    name: key,
+                                    label: 'fallback',
+                                    tags: [],
+                                    credentials: { uri: val },
+                                };
+                                return cachedValue;
+                            }
+                        }
+                    }
+                    if (options.defaultValue !== undefined) {
+                        return options.defaultValue;
+                    }
+                    if (options.required !== false) {
+                        throw new Error(`Cloud Foundry service '${String(serviceNameOrFilter ?? 'default')}' not found and no fallback available`);
+                    }
+                    return undefined;
+                },
+                set(value) {
+                    cachedValue = value;
+                },
+            });
+        }
+        // Constructor parameter injection
+        else if (parameterIndex !== undefined) {
+            const metadata = getOwnMetadata(INJECT_METADATA_KEY, targetClass) || {};
+            metadata[`param_${parameterIndex}`] = token;
+            defineMetadata(INJECT_METADATA_KEY, metadata, targetClass);
+        }
+    };
+}
+/**
+ * Injects Cloud Foundry application metadata (VCAP_APPLICATION).
+ */
+export function VcapApplication(options = {}) {
+    return (
+    // biome-ignore lint/suspicious/noExplicitAny: decorator target
+    targetClass, propertyKey, parameterIndex) => {
+        const token = CF_APPLICATION_TOKEN;
+        if (propertyKey !== undefined && parameterIndex === undefined) {
+            const metadata = getOwnMetadata(INJECT_METADATA_KEY, targetClass) || {};
+            metadata[propertyKey] = token;
+            defineMetadata(INJECT_METADATA_KEY, metadata, targetClass);
+            if (targetClass.constructor && targetClass.constructor !== Object) {
+                const ctorMetadata = getOwnMetadata(INJECT_METADATA_KEY, targetClass.constructor) || {};
+                ctorMetadata[propertyKey] = token;
+                defineMetadata(INJECT_METADATA_KEY, ctorMetadata, targetClass.constructor);
+            }
+            let cachedAppInfo;
+            Object.defineProperty(targetClass, propertyKey, {
+                configurable: true,
+                enumerable: true,
+                get() {
+                    if (cachedAppInfo !== undefined)
+                        return cachedAppInfo;
+                    const container = options.container ?? useContainer();
+                    if (container && typeof container.resolve === 'function') {
+                        try {
+                            const res = container.resolve(token);
+                            if (res !== undefined && res !== null) {
+                                cachedAppInfo = res;
+                                return cachedAppInfo;
+                            }
+                        }
+                        catch {
+                            // fallback
+                        }
+                    }
+                    const info = getDefaultEnvironment().getApplicationInfo();
+                    if (!info && options.required === true) {
+                        throw new Error('Cloud Foundry application info (VCAP_APPLICATION) is required but not present');
+                    }
+                    cachedAppInfo = info;
+                    return cachedAppInfo;
+                },
+                set(value) {
+                    cachedAppInfo = value;
+                },
+            });
+        }
+        else if (parameterIndex !== undefined) {
+            const metadata = getOwnMetadata(INJECT_METADATA_KEY, targetClass) || {};
+            metadata[`param_${parameterIndex}`] = token;
+            defineMetadata(INJECT_METADATA_KEY, metadata, targetClass);
+        }
+    };
+}
+/**
+ * Class decorator that enables Cloud Foundry connector auto-configuration on the DI container.
+ */
+export function EnableCloudFoundryConnectors(options = {}) {
+    // biome-ignore lint/suspicious/noExplicitAny: class constructor
+    return (ctor) => {
+        bindCloudFoundryConnectors(options.container, options);
+        return ctor;
+    };
+}
+function deriveServiceToken(serviceNameOrFilter) {
+    if (typeof serviceNameOrFilter === 'string') {
+        return `cf:service:${serviceNameOrFilter}`;
+    }
+    if (serviceNameOrFilter &&
+        typeof serviceNameOrFilter === 'object' &&
+        'name' in serviceNameOrFilter &&
+        typeof serviceNameOrFilter.name === 'string') {
+        return `cf:service:${serviceNameOrFilter.name}`;
+    }
+    if (serviceNameOrFilter &&
+        typeof serviceNameOrFilter === 'object' &&
+        'label' in serviceNameOrFilter &&
+        typeof serviceNameOrFilter.label === 'string') {
+        return `cf:service:${serviceNameOrFilter.label}`;
+    }
+    return 'cf:service:default';
+}

package/dist/detector.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Utility class for detecting Cloud Foundry runtime environments.
+ */
+export declare class CloudFoundryDetector {
+    /**
+     * Returns true if running within a Cloud Foundry runtime environment
+     * (determined by presence of VCAP_APPLICATION or VCAP_SERVICES).
+     */
+    static isCloudFoundry(env?: Record<string, string | undefined>): boolean;
+    /**
+     * Retrieves raw VCAP_APPLICATION JSON string from environment.
+     */
+    static getApplicationJson(env?: Record<string, string | undefined>): string | undefined;
+    /**
+     * Retrieves raw VCAP_SERVICES JSON string from environment.
+     */
+    static getServicesJson(env?: Record<string, string | undefined>): string | undefined;
+}
+/**
+ * Convenient standalone check for Cloud Foundry runtime.
+ */
+export declare function isCloudFoundry(env?: Record<string, string | undefined>): boolean;

package/dist/detector.js

@@ -0,0 +1,35 @@
+/**
+ * Utility class for detecting Cloud Foundry runtime environments.
+ */
+export class CloudFoundryDetector {
+    /**
+     * Returns true if running within a Cloud Foundry runtime environment
+     * (determined by presence of VCAP_APPLICATION or VCAP_SERVICES).
+     */
+    static isCloudFoundry(env = process.env) {
+        const vcapApp = env.VCAP_APPLICATION;
+        const vcapServices = env.VCAP_SERVICES;
+        return Boolean((typeof vcapApp === 'string' && vcapApp.trim().length > 0) ||
+            (typeof vcapServices === 'string' && vcapServices.trim().length > 0));
+    }
+    /**
+     * Retrieves raw VCAP_APPLICATION JSON string from environment.
+     */
+    static getApplicationJson(env = process.env) {
+        const val = env.VCAP_APPLICATION;
+        return typeof val === 'string' && val.trim().length > 0 ? val.trim() : undefined;
+    }
+    /**
+     * Retrieves raw VCAP_SERVICES JSON string from environment.
+     */
+    static getServicesJson(env = process.env) {
+        const val = env.VCAP_SERVICES;
+        return typeof val === 'string' && val.trim().length > 0 ? val.trim() : undefined;
+    }
+}
+/**
+ * Convenient standalone check for Cloud Foundry runtime.
+ */
+export function isCloudFoundry(env = process.env) {
+    return CloudFoundryDetector.isCloudFoundry(env);
+}

package/dist/environment.d.ts

@@ -0,0 +1,62 @@
+import { type ServiceInfoCreatorRegistry } from './spi/registry.js';
+import type { AmqpServiceInfo, BlobStorageServiceInfo, CloudFoundryApplicationInfo, CloudFoundryServiceInfo, LocalFallbackOptions, RedisServiceInfo, RelationalServiceInfo, ServiceFilter, UserProvidedServiceInfo } from './types.js';
+export interface CloudFoundryEnvironmentOptions {
+    /** Custom environment dictionary (defaults to process.env) */
+    env?: Record<string, string | undefined>;
+    /** Custom service info creator registry */
+    registry?: ServiceInfoCreatorRegistry;
+    /** Options or boolean for local fallback */
+    localFallback?: boolean | LocalFallbackOptions;
+}
+export declare class CloudFoundryEnvironment {
+    private readonly env;
+    private readonly registry;
+    private readonly localFallbackOptions;
+    private appInfo;
+    private services;
+    constructor(options?: CloudFoundryEnvironmentOptions);
+    /**
+     * Returns true if running within a Cloud Foundry runtime.
+     */
+    isCloudFoundry(): boolean;
+    /**
+     * Returns parsed CloudFoundryApplicationInfo or null if not running in CF.
+     */
+    getApplicationInfo(): CloudFoundryApplicationInfo | null;
+    /**
+     * Retrieves all discovered Cloud Foundry services, applying optional filtering.
+     */
+    getServiceInfos<T extends CloudFoundryServiceInfo = CloudFoundryServiceInfo>(filter?: ServiceFilter | string | RegExp): readonly T[];
+    /**
+     * Retrieves a single service by name, filter, or returns the first matching service.
+     */
+    getServiceInfo<T extends CloudFoundryServiceInfo = CloudFoundryServiceInfo>(serviceNameOrFilter?: string | RegExp | ServiceFilter): T | null;
+    /**
+     * Retrieves relational database service info (PostgreSQL, MySQL, MariaDB, SQLite).
+     */
+    getRelationalServiceInfo(filter?: string | RegExp | ServiceFilter): RelationalServiceInfo | null;
+    /**
+     * Retrieves Redis service info.
+     */
+    getRedisServiceInfo(filter?: string | RegExp | ServiceFilter): RedisServiceInfo | null;
+    /**
+     * Retrieves AMQP / RabbitMQ service info.
+     */
+    getAmqpServiceInfo(filter?: string | RegExp | ServiceFilter): AmqpServiceInfo | null;
+    /**
+     * Retrieves Blob Storage / S3 service info.
+     */
+    getBlobStorageServiceInfo(filter?: string | RegExp | ServiceFilter): BlobStorageServiceInfo | null;
+    /**
+     * Retrieves User-Provided service info.
+     */
+    getUserProvidedServiceInfo(filter?: string | RegExp | ServiceFilter): UserProvidedServiceInfo | null;
+    /**
+     * Retrieves raw credentials map for a service.
+     */
+    getServiceCredentials<T = Record<string, unknown>>(serviceName: string): T | null;
+    private ensureServicesLoaded;
+    private buildLocalFallbackServices;
+}
+export declare function getDefaultEnvironment(): CloudFoundryEnvironment;
+export declare function resetDefaultEnvironment(): void;