@bloomneo/appkit 1.5.1 → 1.5.2

package/dist/util/defaults.js

@@ -8,7 +8,7 @@
  * @llm-rule NOTE: Called once at startup, cached globally for performance like other modules
  */
 /**
- * Gets smart defaults using VOILA_UTIL_* environment variables
+ * Gets smart defaults using BLOOM_UTIL_* environment variables
  * @llm-rule WHEN: App startup to get production-ready utility configuration
  * @llm-rule AVOID: Calling repeatedly - expensive validation, cache the result
  * @llm-rule NOTE: Called once at startup, cached globally for performance
@@ -23,36 +23,36 @@ export function getSmartDefaults() {
         version: process.env.npm_package_version || '1.0.0',
         // Cache configuration with direct environment access
         cache: {
-            enabled: process.env.VOILA_UTIL_CACHE !== 'false' && !isTest,
-            maxSize: parseInt(process.env.VOILA_UTIL_CACHE_SIZE || '1000'),
-            ttl: parseInt(process.env.VOILA_UTIL_CACHE_TTL || '300000'), // 5 minutes
+            enabled: process.env.BLOOM_UTIL_CACHE !== 'false' && !isTest,
+            maxSize: parseInt(process.env.BLOOM_UTIL_CACHE_SIZE || '1000'),
+            ttl: parseInt(process.env.BLOOM_UTIL_CACHE_TTL || '300000'), // 5 minutes
         },
         // Performance optimization settings
         performance: {
-            enabled: process.env.VOILA_UTIL_PERFORMANCE !== 'false',
-            memoization: process.env.VOILA_UTIL_MEMOIZATION !== 'false' && !isTest,
-            largeArrayThreshold: parseInt(process.env.VOILA_UTIL_ARRAY_THRESHOLD || '10000'),
-            chunkSizeLimit: parseInt(process.env.VOILA_UTIL_CHUNK_LIMIT || '100000'),
+            enabled: process.env.BLOOM_UTIL_PERFORMANCE !== 'false',
+            memoization: process.env.BLOOM_UTIL_MEMOIZATION !== 'false' && !isTest,
+            largeArrayThreshold: parseInt(process.env.BLOOM_UTIL_ARRAY_THRESHOLD || '10000'),
+            chunkSizeLimit: parseInt(process.env.BLOOM_UTIL_CHUNK_LIMIT || '100000'),
         },
         // Debug configuration - enabled in development
         debug: {
-            enabled: process.env.VOILA_UTIL_DEBUG === 'true' || isDevelopment,
-            logOperations: process.env.VOILA_UTIL_LOG_OPS === 'true' || isDevelopment,
-            trackPerformance: process.env.VOILA_UTIL_TRACK_PERF === 'true' || isDevelopment,
+            enabled: process.env.BLOOM_UTIL_DEBUG === 'true' || isDevelopment,
+            logOperations: process.env.BLOOM_UTIL_LOG_OPS === 'true' || isDevelopment,
+            trackPerformance: process.env.BLOOM_UTIL_TRACK_PERF === 'true' || isDevelopment,
         },
         // Slugify configuration with locale support
         slugify: {
-            lowercase: process.env.VOILA_UTIL_SLUGIFY_LOWERCASE !== 'false',
-            strict: process.env.VOILA_UTIL_SLUGIFY_STRICT === 'true',
-            locale: process.env.VOILA_UTIL_LOCALE || 'en',
-            replacement: process.env.VOILA_UTIL_SLUGIFY_REPLACEMENT || '-',
+            lowercase: process.env.BLOOM_UTIL_SLUGIFY_LOWERCASE !== 'false',
+            strict: process.env.BLOOM_UTIL_SLUGIFY_STRICT === 'true',
+            locale: process.env.BLOOM_UTIL_LOCALE || 'en',
+            replacement: process.env.BLOOM_UTIL_SLUGIFY_REPLACEMENT || '-',
         },
         // Format configuration for locale-aware formatting
         format: {
-            locale: process.env.VOILA_UTIL_LOCALE || 'en-US',
-            currency: process.env.VOILA_UTIL_CURRENCY || 'USD',
-            dateFormat: process.env.VOILA_UTIL_DATE_FORMAT || 'YYYY-MM-DD',
-            numberPrecision: parseInt(process.env.VOILA_UTIL_NUMBER_PRECISION || '2'),
+            locale: process.env.BLOOM_UTIL_LOCALE || 'en-US',
+            currency: process.env.BLOOM_UTIL_CURRENCY || 'USD',
+            dateFormat: process.env.BLOOM_UTIL_DATE_FORMAT || 'YYYY-MM-DD',
+            numberPrecision: parseInt(process.env.BLOOM_UTIL_NUMBER_PRECISION || '2'),
         },
         // Environment information
         environment: {
@@ -72,69 +72,69 @@ export function getSmartDefaults() {
 function validateEnvironment() {
     const nodeEnv = process.env.NODE_ENV || 'development';
     // Validate cache configuration
-    const cacheSize = process.env.VOILA_UTIL_CACHE_SIZE;
+    const cacheSize = process.env.BLOOM_UTIL_CACHE_SIZE;
     if (cacheSize) {
         const cacheSizeNum = parseInt(cacheSize);
         if (isNaN(cacheSizeNum) || cacheSizeNum <= 0) {
-            throw new Error(`Invalid VOILA_UTIL_CACHE_SIZE: "${cacheSize}". Must be a positive number.`);
+            throw new Error(`Invalid BLOOM_UTIL_CACHE_SIZE: "${cacheSize}". Must be a positive number.`);
         }
         if (cacheSizeNum > 100000) {
             console.warn(`[Bloomneo AppKit] Large cache size: ${cacheSizeNum}. This may impact memory usage.`);
         }
     }
     // Validate cache TTL
-    const cacheTTL = process.env.VOILA_UTIL_CACHE_TTL;
+    const cacheTTL = process.env.BLOOM_UTIL_CACHE_TTL;
     if (cacheTTL) {
         const cacheTTLNum = parseInt(cacheTTL);
         if (isNaN(cacheTTLNum) || cacheTTLNum <= 0) {
-            throw new Error(`Invalid VOILA_UTIL_CACHE_TTL: "${cacheTTL}". Must be a positive number (milliseconds).`);
+            throw new Error(`Invalid BLOOM_UTIL_CACHE_TTL: "${cacheTTL}". Must be a positive number (milliseconds).`);
         }
     }
     // Validate array threshold
-    const arrayThreshold = process.env.VOILA_UTIL_ARRAY_THRESHOLD;
+    const arrayThreshold = process.env.BLOOM_UTIL_ARRAY_THRESHOLD;
     if (arrayThreshold) {
         const thresholdNum = parseInt(arrayThreshold);
         if (isNaN(thresholdNum) || thresholdNum <= 0) {
-            throw new Error(`Invalid VOILA_UTIL_ARRAY_THRESHOLD: "${arrayThreshold}". Must be a positive number.`);
+            throw new Error(`Invalid BLOOM_UTIL_ARRAY_THRESHOLD: "${arrayThreshold}". Must be a positive number.`);
         }
     }
     // Validate chunk size limit
-    const chunkLimit = process.env.VOILA_UTIL_CHUNK_LIMIT;
+    const chunkLimit = process.env.BLOOM_UTIL_CHUNK_LIMIT;
     if (chunkLimit) {
         const chunkLimitNum = parseInt(chunkLimit);
         if (isNaN(chunkLimitNum) || chunkLimitNum <= 0) {
-            throw new Error(`Invalid VOILA_UTIL_CHUNK_LIMIT: "${chunkLimit}". Must be a positive number.`);
+            throw new Error(`Invalid BLOOM_UTIL_CHUNK_LIMIT: "${chunkLimit}". Must be a positive number.`);
         }
     }
     // Validate number precision
-    const numberPrecision = process.env.VOILA_UTIL_NUMBER_PRECISION;
+    const numberPrecision = process.env.BLOOM_UTIL_NUMBER_PRECISION;
     if (numberPrecision) {
         const precisionNum = parseInt(numberPrecision);
         if (isNaN(precisionNum) || precisionNum < 0 || precisionNum > 20) {
-            throw new Error(`Invalid VOILA_UTIL_NUMBER_PRECISION: "${numberPrecision}". Must be between 0 and 20.`);
+            throw new Error(`Invalid BLOOM_UTIL_NUMBER_PRECISION: "${numberPrecision}". Must be between 0 and 20.`);
         }
     }
     // Validate locale if provided
-    const locale = process.env.VOILA_UTIL_LOCALE;
+    const locale = process.env.BLOOM_UTIL_LOCALE;
     if (locale && !isValidLocale(locale)) {
         console.warn(`[Bloomneo AppKit] Invalid locale: "${locale}". Using default 'en-US'.`);
     }
     // Validate currency if provided
-    const currency = process.env.VOILA_UTIL_CURRENCY;
+    const currency = process.env.BLOOM_UTIL_CURRENCY;
     if (currency && !isValidCurrency(currency)) {
         console.warn(`[Bloomneo AppKit] Invalid currency: "${currency}". Using default 'USD'.`);
     }
     // Validate slugify replacement
-    const replacement = process.env.VOILA_UTIL_SLUGIFY_REPLACEMENT;
+    const replacement = process.env.BLOOM_UTIL_SLUGIFY_REPLACEMENT;
     if (replacement && replacement.length > 5) {
         console.warn(`[Bloomneo AppKit] Long slugify replacement: "${replacement}". Consider using shorter replacement.`);
     }
     // Production-specific warnings
     if (nodeEnv === 'production') {
-        if (process.env.VOILA_UTIL_DEBUG === 'true') {
+        if (process.env.BLOOM_UTIL_DEBUG === 'true') {
             console.warn('[Bloomneo AppKit] Debug mode enabled in production. This may impact performance.');
         }
-        if (process.env.VOILA_UTIL_LOG_OPS === 'true') {
+        if (process.env.BLOOM_UTIL_LOG_OPS === 'true') {
             console.warn('[Bloomneo AppKit] Operation logging enabled in production. This may impact performance.');
         }
     }

package/dist/util/env.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Environment variable reader for @bloomneo/appkit.
+ *
+ * Canonical prefix is `BLOOM_`. The legacy `VOILA_*` prefix from the original
+ * `@voilajsx/appkit` package was removed entirely in 1.5.2 — there is no
+ * backwards-compatibility, no fallback, no deprecation warning. Consumers
+ * upgrading must rename their env vars in one go.
+ *
+ * Internal use only. Consumers should call `configClass.get()` instead of
+ * touching env vars directly. This file exists so future code has one
+ * canonical helper for reading env vars, instead of scattering
+ * `process.env.BLOOM_*` calls across the codebase.
+ *
+ * @file src/util/env.ts
+ */
+/**
+ * Read an env var by its bare name (no prefix).
+ *
+ * @example
+ *   env('AUTH_SECRET')         // → process.env.BLOOM_AUTH_SECRET
+ *   env('DB_TENANT')           // → process.env.BLOOM_DB_TENANT
+ *   env('FOO', 'default-val')  // → returns 'default-val' if BLOOM_FOO unset
+ */
+export declare function env(name: string, fallback?: string): string | undefined;
+/**
+ * Read a numeric env var. Returns the fallback if the var is unset or
+ * the value can't be parsed as a finite number.
+ */
+export declare function envNumber(name: string, fallback: number): number;
+/**
+ * Read a boolean env var. Truthy: 'true' / '1' / 'yes' / 'on' (case-insensitive).
+ * Returns the fallback if the var is unset.
+ */
+export declare function envBool(name: string, fallback: boolean): boolean;
+//# sourceMappingURL=env.d.ts.map

package/dist/util/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/util/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;GAOG;AACH,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGvE;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKhE;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAKhE"}

package/dist/util/env.js

@@ -0,0 +1,50 @@
+/**
+ * Environment variable reader for @bloomneo/appkit.
+ *
+ * Canonical prefix is `BLOOM_`. The legacy `VOILA_*` prefix from the original
+ * `@voilajsx/appkit` package was removed entirely in 1.5.2 — there is no
+ * backwards-compatibility, no fallback, no deprecation warning. Consumers
+ * upgrading must rename their env vars in one go.
+ *
+ * Internal use only. Consumers should call `configClass.get()` instead of
+ * touching env vars directly. This file exists so future code has one
+ * canonical helper for reading env vars, instead of scattering
+ * `process.env.BLOOM_*` calls across the codebase.
+ *
+ * @file src/util/env.ts
+ */
+/**
+ * Read an env var by its bare name (no prefix).
+ *
+ * @example
+ *   env('AUTH_SECRET')         // → process.env.BLOOM_AUTH_SECRET
+ *   env('DB_TENANT')           // → process.env.BLOOM_DB_TENANT
+ *   env('FOO', 'default-val')  // → returns 'default-val' if BLOOM_FOO unset
+ */
+export function env(name, fallback) {
+    const value = process.env[`BLOOM_${name}`];
+    return value !== undefined ? value : fallback;
+}
+/**
+ * Read a numeric env var. Returns the fallback if the var is unset or
+ * the value can't be parsed as a finite number.
+ */
+export function envNumber(name, fallback) {
+    const raw = env(name);
+    if (raw === undefined)
+        return fallback;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+/**
+ * Read a boolean env var. Truthy: 'true' / '1' / 'yes' / 'on' (case-insensitive).
+ * Returns the fallback if the var is unset.
+ */
+export function envBool(name, fallback) {
+    const raw = env(name);
+    if (raw === undefined)
+        return fallback;
+    const v = raw.toLowerCase();
+    return v === 'true' || v === '1' || v === 'yes' || v === 'on';
+}
+//# sourceMappingURL=env.js.map

package/dist/util/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/util/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,GAAG,CAAC,IAAY,EAAE,QAAiB;IACjD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;IAC3C,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC;AAChD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,QAAgB;IACtD,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;IACtB,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IACvC,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3B,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;AACrD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,QAAiB;IACrD,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;IACtB,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IACvC,MAAM,CAAC,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;IAC5B,OAAO,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,IAAI,CAAC;AAChE,CAAC"}

package/dist/util/errors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Educational runtime errors for @bloomneo/appkit.
+ *
+ * Modules throw these (instead of plain TypeError or generic Error) so that
+ * humans AND AI coding agents reading the error message get an actionable
+ * fix-it-now message that names the missing thing AND points at the canonical
+ * pattern in AGENTS.md or the relevant example file.
+ *
+ * Format is intentionally consistent across all 12 modules:
+ *
+ *   [@bloomneo/appkit] <Module> requires <thing>. <reason>.
+ *   See: <docs URL or example file>
+ *
+ * Agents that read errors and self-correct will fetch the link and recover
+ * on the next iteration. Without this, agents get cryptic "X is undefined"
+ * messages and have to guess.
+ *
+ * @file src/util/errors.ts
+ */
+export declare class AppKitError extends Error {
+    readonly module: string;
+    readonly docsUrl: string;
+    constructor(module: string, message: string, slug?: string);
+}
+/**
+ * Throw if a required env var is missing. Use at module init / first .get()
+ * call so the error is loud and immediate, not deferred to the first request.
+ *
+ * @example
+ *   requireEnv('Auth', 'BLOOM_AUTH_SECRET',
+ *     'Set this to a 32+ character random string. See examples/.env.example.');
+ */
+export declare function requireEnv(module: string, varName: string, hint?: string): string;
+/**
+ * Throw if `value` is missing or wrongly typed. Use at the top of public
+ * methods that depend on caller-provided data.
+ *
+ * @example
+ *   const auth = authClass.get();
+ *   auth.signToken = (payload) => {
+ *     requireProp('Auth', 'signToken.payload', payload);
+ *     // ...
+ *   };
+ */
+export declare function requireProp<T>(module: string, prop: string, value: T | undefined | null, hint?: string): T;
+/**
+ * Lighter-weight version that only warns in development. Use for nice-to-have
+ * conventions ("you should pass a 32-char secret, not a 16-char one") that
+ * shouldn't crash a production app on startup.
+ */
+export declare function warnInDev(module: string, message: string, slug?: string): void;
+//# sourceMappingURL=errors.d.ts.map

package/dist/util/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/util/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAO3D;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CASjF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,CAAC,GAAG,SAAS,GAAG,IAAI,EAC3B,IAAI,CAAC,EAAE,MAAM,GACZ,CAAC,CAQH;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAK9E"}

package/dist/util/errors.js

@@ -0,0 +1,82 @@
+/**
+ * Educational runtime errors for @bloomneo/appkit.
+ *
+ * Modules throw these (instead of plain TypeError or generic Error) so that
+ * humans AND AI coding agents reading the error message get an actionable
+ * fix-it-now message that names the missing thing AND points at the canonical
+ * pattern in AGENTS.md or the relevant example file.
+ *
+ * Format is intentionally consistent across all 12 modules:
+ *
+ *   [@bloomneo/appkit] <Module> requires <thing>. <reason>.
+ *   See: <docs URL or example file>
+ *
+ * Agents that read errors and self-correct will fetch the link and recover
+ * on the next iteration. Without this, agents get cryptic "X is undefined"
+ * messages and have to guess.
+ *
+ * @file src/util/errors.ts
+ */
+const DOCS_BASE = 'https://github.com/bloomneo/appkit/blob/main/AGENTS.md';
+export class AppKitError extends Error {
+    module;
+    docsUrl;
+    constructor(module, message, slug) {
+        const url = slug ? `${DOCS_BASE}#${slug}` : DOCS_BASE;
+        super(`[@bloomneo/appkit] ${module}: ${message}\nSee: ${url}`);
+        this.name = 'AppKitError';
+        this.module = module;
+        this.docsUrl = url;
+    }
+}
+/**
+ * Throw if a required env var is missing. Use at module init / first .get()
+ * call so the error is loud and immediate, not deferred to the first request.
+ *
+ * @example
+ *   requireEnv('Auth', 'BLOOM_AUTH_SECRET',
+ *     'Set this to a 32+ character random string. See examples/.env.example.');
+ */
+export function requireEnv(module, varName, hint) {
+    const value = process.env[varName];
+    if (value === undefined || value === '') {
+        const msg = hint
+            ? `requires env var \`${varName}\` to be set. ${hint}`
+            : `requires env var \`${varName}\` to be set.`;
+        throw new AppKitError(module, msg, 'environment-variables');
+    }
+    return value;
+}
+/**
+ * Throw if `value` is missing or wrongly typed. Use at the top of public
+ * methods that depend on caller-provided data.
+ *
+ * @example
+ *   const auth = authClass.get();
+ *   auth.signToken = (payload) => {
+ *     requireProp('Auth', 'signToken.payload', payload);
+ *     // ...
+ *   };
+ */
+export function requireProp(module, prop, value, hint) {
+    if (value === undefined || value === null) {
+        const msg = hint
+            ? `\`${prop}\` is required. ${hint}`
+            : `\`${prop}\` is required.`;
+        throw new AppKitError(module, msg);
+    }
+    return value;
+}
+/**
+ * Lighter-weight version that only warns in development. Use for nice-to-have
+ * conventions ("you should pass a 32-char secret, not a 16-char one") that
+ * shouldn't crash a production app on startup.
+ */
+export function warnInDev(module, message, slug) {
+    if (process.env.NODE_ENV === 'production')
+        return;
+    const url = slug ? `${DOCS_BASE}#${slug}` : DOCS_BASE;
+    // eslint-disable-next-line no-console
+    console.warn(`[@bloomneo/appkit] ${module}: ${message}\nSee: ${url}`);
+}
+//# sourceMappingURL=errors.js.map

package/dist/util/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/util/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,SAAS,GAAG,wDAAwD,CAAC;AAE3E,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,MAAM,CAAS;IACf,OAAO,CAAS;IAEzB,YAAY,MAAc,EAAE,OAAe,EAAE,IAAa;QACxD,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,SAAS,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QACtD,KAAK,CAAC,sBAAsB,MAAM,KAAK,OAAO,UAAU,GAAG,EAAE,CAAC,CAAC;QAC/D,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC;IACrB,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,MAAc,EAAE,OAAe,EAAE,IAAa;IACvE,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;QACxC,MAAM,GAAG,GAAG,IAAI;YACd,CAAC,CAAC,sBAAsB,OAAO,iBAAiB,IAAI,EAAE;YACtD,CAAC,CAAC,sBAAsB,OAAO,eAAe,CAAC;QACjD,MAAM,IAAI,WAAW,CAAC,MAAM,EAAE,GAAG,EAAE,uBAAuB,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CACzB,MAAc,EACd,IAAY,EACZ,KAA2B,EAC3B,IAAa;IAEb,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1C,MAAM,GAAG,GAAG,IAAI;YACd,CAAC,CAAC,KAAK,IAAI,mBAAmB,IAAI,EAAE;YACpC,CAAC,CAAC,KAAK,IAAI,iBAAiB,CAAC;QAC/B,MAAM,IAAI,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,MAAc,EAAE,OAAe,EAAE,IAAa;IACtE,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;QAAE,OAAO;IAClD,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,SAAS,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACtD,sCAAsC;IACtC,OAAO,CAAC,IAAI,CAAC,sBAAsB,MAAM,KAAK,OAAO,UAAU,GAAG,EAAE,CAAC,CAAC;AACxE,CAAC"}

package/examples/.env.example

@@ -0,0 +1,80 @@
+# Bloomneo AppKit — canonical environment template
+#
+# Copy this to `.env` in your project root and fill in real values.
+# All env vars use the BLOOM_ prefix. The legacy VOILA_ prefix from
+# @voilajsx/appkit was removed in 1.5.2 — there is no fallback.
+#
+# Generate secrets with: openssl rand -base64 32
+
+# ──────────────────────────────────────────────────────────────────────
+# REQUIRED for production
+# ──────────────────────────────────────────────────────────────────────
+
+# JWT signing key for authClass.get().signToken() / verifyToken()
+# Minimum 32 characters.
+BLOOM_AUTH_SECRET=replace-me-with-openssl-rand-base64-32
+
+# Prisma connection string. Any Prisma-supported URL works.
+DATABASE_URL=postgresql://user:pass@localhost:5432/myapp
+
+# CSRF token signing for securityClass.get().csrf() / requireCsrf()
+# Minimum 32 characters.
+BLOOM_SECURITY_CSRF_SECRET=replace-me-with-openssl-rand-base64-32
+
+# AES-256-GCM encryption key for securityClass.get().encrypt() / decrypt()
+# Exactly 64 hex characters (32 bytes).
+BLOOM_SECURITY_ENCRYPTION_KEY=replace-me-with-openssl-rand-hex-32
+
+# ──────────────────────────────────────────────────────────────────────
+# OPTIONAL — auto-scaling kicks in when set
+# ──────────────────────────────────────────────────────────────────────
+
+# Distributed cache + queue + events (memory by default)
+# REDIS_URL=redis://localhost:6379
+
+# Cloud storage (local disk by default)
+# AWS_S3_BUCKET=my-bucket
+# AWS_REGION=us-east-1
+# AWS_ACCESS_KEY_ID=...
+# AWS_SECRET_ACCESS_KEY=...
+
+# Cloudflare R2 (alternative to S3)
+# R2_BUCKET=my-bucket
+# R2_ACCOUNT_ID=...
+# R2_ACCESS_KEY_ID=...
+# R2_SECRET_ACCESS_KEY=...
+
+# Production email (console transport by default)
+# RESEND_API_KEY=re_...
+# or
+# SMTP_HOST=smtp.example.com
+# SMTP_PORT=587
+# SMTP_USER=...
+# SMTP_PASS=...
+
+# Multi-tenant database filtering
+# When set to "auto", database queries auto-filter by tenant_id.
+# BLOOM_DB_TENANT=auto
+
+# Per-organization databases (multi-org SaaS)
+# Each ORG_<NAME> is a separate connection string used by databaseClass.org('<name>').get()
+# ORG_ACME=postgresql://acme.aws.com/prod
+# ORG_GLOBEX=postgresql://globex.aws.com/prod
+
+# Background queue persistence (memory by default)
+# BLOOM_QUEUE_DB=true   # use database-backed queue when REDIS_URL not set
+
+# Logger transports
+# BLOOM_LOGGER_FILE_PATH=/var/log/myapp.log
+# BLOOM_LOGGER_HTTP_URL=https://logs.example.com/ingest
+# BLOOM_LOGGER_WEBHOOK_URL=https://hooks.slack.com/services/...
+
+# Service identification (used by logger metadata)
+# BLOOM_SERVICE_NAME=myapp
+# BLOOM_SERVICE_VERSION=1.0.0
+
+# Default user password for seeds (development only)
+# DEFAULT_USER_PASSWORD=changeme123
+
+# Frontend API key (for browser → API auth — generated by `appkit generate app`)
+# BLOOM_FRONTEND_KEY=bloom_<random>

package/examples/README.md

@@ -0,0 +1,16 @@
+# Examples
+
+One minimal `.ts` file per module. Each example is the smallest runnable shape
+of the canonical pattern — copy, modify the data, ship.
+
+For composed multi-module patterns (auth-protected CRUD, multi-tenant API,
+file upload + queue, real-time chat), see [`../cookbook/`](../cookbook/).
+
+## Conventions
+
+- Always import from `@bloomneo/appkit` (or the subpath form).
+- Always use `xxxClass.get()` to obtain a module instance.
+- Always cache the module instance at module scope, not inside route handlers.
+- Use semantic error throwers (`error.badRequest()`, `error.unauthorized()`),
+  never `throw new Error(...)` in route handlers.
+- See [`.env.example`](./.env.example) for the canonical environment template.