@zintrust/core 0.1.5 → 0.1.6

package/src/templates/project/basic/config/type.ts.tpl

@@ -0,0 +1,414 @@
+import { Env } from '@config/env';
+import type { Middleware as MiddlewareFn } from '@middleware/MiddlewareStack';
+
+export type Environment =
+  | 'development'
+  | 'dev'
+  | 'production'
+  | 'prod'
+  | 'pro'
+  | 'testing'
+  | 'test';
+export type StartMode = 'development' | 'production' | 'testing';
+
+export type EnvGetValue = ReturnType<typeof Env.get>;
+export type EnvGetBoolValue = ReturnType<typeof Env.getBool>;
+
+export type LocalStorageDriverConfig = {
+  driver: 'local';
+  root: EnvGetValue;
+  url: EnvGetValue;
+  visibility: EnvGetValue;
+};
+
+export type S3StorageDriverConfig = {
+  driver: 's3';
+  accessKeyId: EnvGetValue;
+  secretAccessKey: EnvGetValue;
+  region: typeof Env.AWS_REGION;
+  bucket: EnvGetValue;
+  url: EnvGetValue;
+  endpoint: EnvGetValue;
+  usePathStyleUrl: EnvGetBoolValue;
+};
+
+export type R2StorageDriverConfig = {
+  driver: 'r2';
+  accessKeyId: EnvGetValue;
+  secretAccessKey: EnvGetValue;
+  region: EnvGetValue;
+  bucket: EnvGetValue;
+  endpoint: EnvGetValue;
+  url: EnvGetValue;
+};
+
+export type GcsStorageDriverConfig = {
+  driver: 'gcs';
+  projectId: EnvGetValue;
+  keyFile: EnvGetValue;
+  bucket: EnvGetValue;
+  url: EnvGetValue;
+};
+
+export type StorageDrivers = {
+  local: LocalStorageDriverConfig;
+  s3: S3StorageDriverConfig;
+  r2: R2StorageDriverConfig;
+  gcs: GcsStorageDriverConfig;
+};
+
+export type StorageDriverName = keyof StorageDrivers;
+export type StorageDriverConfig = StorageDrivers[StorageDriverName];
+
+export type StorageConfigRuntime = {
+  readonly default: string;
+  readonly drivers: StorageDrivers;
+};
+
+export type StartupConfigValidationError = {
+  key: string;
+  value: unknown;
+  message: string;
+};
+
+export type StartupConfigValidationResult = {
+  valid: boolean;
+  errors: StartupConfigValidationError[];
+};
+
+export interface CloudflareKV {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;
+  delete(key: string): Promise<void>;
+  list(options?: { prefix?: string }): Promise<{ keys: { name: string }[] }>;
+}
+
+export interface SecretConfig {
+  platform: 'aws' | 'cloudflare' | 'deno' | 'local';
+  region?: string;
+  kv?: CloudflareKV; // Cloudflare KV namespace
+}
+
+export interface SecretValue {
+  key: string;
+  value: string;
+  expiresAt?: number;
+  rotationEnabled?: boolean;
+}
+
+export interface GetSecretOptions {
+  cacheTtl?: number; // Cache time-to-live in milliseconds
+  throwIfMissing?: boolean;
+}
+
+export interface SetSecretOptions {
+  expirationTtl?: number; // Expiration time-to-live in seconds
+  metadata?: Record<string, unknown>;
+}
+
+export interface SecretsManagerInstance {
+  getSecret(key: string, options?: GetSecretOptions): Promise<string>;
+  setSecret(key: string, value: string, options?: SetSecretOptions): Promise<void>;
+  deleteSecret(key: string): Promise<void>;
+  rotateSecret(key: string): Promise<void>;
+  listSecrets(pattern?: string): Promise<string[]>;
+  clearCache(key?: string): void;
+}
+
+export type QueueDriverName = 'sync' | 'database' | 'redis' | 'rabbitmq' | 'sqs';
+
+export type SyncQueueDriverConfig = {
+  driver: 'sync';
+};
+
+export type DatabaseQueueDriverConfig = {
+  driver: 'database';
+  table: string;
+  connection: string;
+};
+
+export type RedisQueueDriverConfig = {
+  driver: 'redis';
+  host: string;
+  port: number;
+  password?: string;
+  database: number;
+};
+
+export type RabbitMqQueueDriverConfig = {
+  driver: 'rabbitmq';
+  host: string;
+  port: number;
+  username: string;
+  password: string;
+  vhost: string;
+};
+
+export type SqsQueueDriverConfig = {
+  driver: 'sqs';
+  key?: string;
+  secret?: string;
+  region: string;
+  queueUrl?: string;
+};
+
+export type QueueDriversConfig = {
+  sync: SyncQueueDriverConfig;
+  database: DatabaseQueueDriverConfig;
+  redis: RedisQueueDriverConfig;
+  rabbitmq: RabbitMqQueueDriverConfig;
+  sqs: SqsQueueDriverConfig;
+};
+
+export type QueueConfigWithDrivers = {
+  default: QueueDriverName;
+  drivers: QueueDriversConfig;
+};
+
+export type KnownNotificationDriverName = 'console' | 'termii' | 'twilio' | 'slack';
+
+export type ConsoleNotificationDriverConfig = { driver: 'console' };
+
+export type TermiiNotificationDriverConfig = {
+  driver: 'termii';
+  apiKey: string;
+  sender: string;
+  endpoint: string;
+};
+
+export type TwilioNotificationDriverConfig = {
+  driver: 'twilio';
+  accountSid: string;
+  authToken: string;
+  fromNumber: string;
+};
+
+export type SlackNotificationDriverConfig = {
+  driver: 'slack';
+  webhookUrl: string;
+};
+
+export type KnownNotificationDriverConfig =
+  | ConsoleNotificationDriverConfig
+  | TermiiNotificationDriverConfig
+  | TwilioNotificationDriverConfig
+  | SlackNotificationDriverConfig;
+
+export type NotificationProviders = {
+  console: ConsoleNotificationDriverConfig;
+  termii: TermiiNotificationDriverConfig;
+  twilio: TwilioNotificationDriverConfig;
+  slack: SlackNotificationDriverConfig;
+};
+
+export type MiddlewareConfigType = {
+  global: MiddlewareFn[];
+  route: Record<string, MiddlewareFn>;
+};
+
+export type MailDriverName = 'disabled' | 'sendgrid' | 'smtp' | 'ses' | 'mailgun';
+
+export type DisabledMailDriverConfig = {
+  driver: 'disabled';
+};
+
+export type SendGridMailDriverConfig = {
+  driver: 'sendgrid';
+  apiKey: string;
+};
+
+export type MailgunMailDriverConfig = {
+  driver: 'mailgun';
+  apiKey: string;
+  domain: string;
+  baseUrl: string;
+};
+
+// Placeholders for future drivers (kept config-first)
+export type SmtpMailDriverConfig = {
+  driver: 'smtp';
+  host: string;
+  port: number;
+  username: string;
+  password: string;
+  secure: boolean | 'starttls';
+};
+
+export type SesMailDriverConfig = {
+  driver: 'ses';
+  region: string;
+};
+
+export type MailDriverConfig =
+  | DisabledMailDriverConfig
+  | SendGridMailDriverConfig
+  | MailgunMailDriverConfig
+  | SmtpMailDriverConfig
+  | SesMailDriverConfig;
+
+export type MailDrivers = {
+  disabled: DisabledMailDriverConfig;
+  sendgrid: SendGridMailDriverConfig;
+  mailgun: MailgunMailDriverConfig;
+  smtp: SmtpMailDriverConfig;
+  ses: SesMailDriverConfig;
+};
+
+export type MailConfigInput = {
+  default: MailDriverName;
+  from: {
+    address: string;
+    name: string;
+  };
+  drivers: MailDrivers;
+};
+
+export type ProcessLike = {
+  env?: Record<string, string | undefined>;
+  execPath?: string;
+  platform?: string;
+};
+
+export type SqliteConnectionConfig = {
+  driver: 'sqlite';
+  database: string;
+  migrations: string;
+};
+
+export type PostgresqlConnectionConfig = {
+  driver: 'postgresql';
+  host: string;
+  port: number;
+  database: string;
+  username: string;
+  password: string;
+  ssl: boolean;
+  pooling: {
+    enabled: boolean;
+    min: number;
+    max: number;
+    idleTimeout: number;
+    connectionTimeout: number;
+  };
+};
+
+export type MysqlConnectionConfig = {
+  driver: 'mysql';
+  host: string;
+  port: number;
+  database: string;
+  username: string;
+  password: string;
+  pooling: {
+    enabled: boolean;
+    min: number;
+    max: number;
+  };
+};
+
+export type DatabaseConnections = {
+  sqlite: SqliteConnectionConfig;
+  postgresql: PostgresqlConnectionConfig;
+  mysql: MysqlConnectionConfig;
+};
+
+export type DatabaseConnectionName = keyof DatabaseConnections;
+export type DatabaseConnectionConfig = DatabaseConnections[DatabaseConnectionName];
+
+export type DatabaseConfigShape = {
+  default: DatabaseConnectionName;
+  connections: DatabaseConnections;
+};
+
+export type WorkersEnv = Record<string, unknown>;
+
+export type KVNamespace = {
+  get(
+    key: string,
+    options?: { type: 'text' | 'json' | 'arrayBuffer' | 'stream' }
+  ): Promise<unknown>;
+  put(
+    key: string,
+    value: string | ReadableStream | ArrayBuffer | FormData,
+    options?: { expiration?: number; expirationTtl?: number; metadata?: unknown }
+  ): Promise<void>;
+  delete(key: string): Promise<void>;
+};
+
+export type MemoryCacheDriverConfig = {
+  driver: 'memory';
+  ttl: number;
+};
+
+export type RedisCacheDriverConfig = {
+  driver: 'redis';
+  host: string;
+  port: number;
+  ttl: number;
+};
+
+export type MongoCacheDriverConfig = {
+  driver: 'mongodb';
+  uri: string;
+  db: string;
+  ttl: number;
+};
+
+export type KvCacheDriverConfig = {
+  driver: 'kv';
+  ttl: number;
+};
+
+export type CacheDriverConfig =
+  | MemoryCacheDriverConfig
+  | RedisCacheDriverConfig
+  | MongoCacheDriverConfig
+  | KvCacheDriverConfig;
+
+export type CacheDrivers = {
+  memory: MemoryCacheDriverConfig;
+  redis: RedisCacheDriverConfig;
+  mongodb: MongoCacheDriverConfig;
+  kv: KvCacheDriverConfig;
+};
+
+export type CacheConfigInput = {
+  default: string;
+  drivers: CacheDrivers;
+};
+
+export type KnownBroadcastDriverName = 'inmemory' | 'pusher' | 'redis' | 'redishttps';
+
+export type InMemoryBroadcastDriverConfig = {
+  driver: 'inmemory';
+};
+
+export type PusherBroadcastDriverConfig = {
+  driver: 'pusher';
+  appId: string;
+  key: string;
+  secret: string;
+  cluster: string;
+  useTLS: boolean;
+};
+
+export type RedisBroadcastDriverConfig = {
+  driver: 'redis';
+  host: string;
+  port: number;
+  password: string;
+  channelPrefix: string;
+};
+
+export type RedisHttpsBroadcastDriverConfig = {
+  driver: 'redishttps';
+  endpoint: string;
+  token: string;
+  channelPrefix: string;
+};
+
+export type KnownBroadcastDriverConfig =
+  | InMemoryBroadcastDriverConfig
+  | PusherBroadcastDriverConfig
+  | RedisBroadcastDriverConfig
+  | RedisHttpsBroadcastDriverConfig;

package/src/templates/project/basic/package.json.tpl

@@ -14,6 +14,7 @@
     "@zintrust/core": "^0.1.4"
   },
   "devDependencies": {
+    "@types/node": "^25.0.3",
     "tsx": "^4.21.0",
     "tsc-alias": "^1.8.16",
     "typescript": "^5.9.3",

package/src/templates/project/basic/routes/api.ts.tpl

@@ -4,7 +4,7 @@
  */
 
 import { UserController } from '@app/Controllers/UserController';
-import { Env } from '@config/env';
+import { Env } from '@zintrust/core';
 import { registerBroadcastRoutes } from '@routes/broadcast';
 import { registerHealthRoutes } from '@routes/health';
 import { registerStorageRoutes } from '@routes/storage';

package/src/templates/project/basic/routes/broadcast.ts.tpl

@@ -25,7 +25,7 @@ export function registerBroadcastRoutes(router: IRouter): void {
       return;
     }
 
-    const { Broadcast } = await import('@broadcast/Broadcast');
+    const { Broadcast } = await import('@zintrust/core');
     const result = await Broadcast.send(channel, event, data);
     res.json({ ok: true, result });
   });

package/src/templates/project/basic/routes/health.ts.tpl

@@ -5,7 +5,7 @@
 
 import { appConfig } from '@/config';
 import { RuntimeHealthProbes } from '@/health/RuntimeHealthProbes';
-import { Env } from '@config/env';
+import { Env } from '@zintrust/core';
 import { Logger } from '@config/logger';
 import { useDatabase } from '@zintrust/core';
 import { QueryBuilder } from '@zintrust/core';

package/src/templates/project/basic/routes/storage.ts.tpl

@@ -1,5 +1,5 @@
 import { HTTP_HEADERS } from '@config/constants';
-import { Env } from '@config/env';
+import { Env } from '@zintrust/core';
 import { type IRouter, Router } from '@zintrust/core';
 import { LocalSignedUrl } from '@storage/LocalSignedUrl';
 import { Storage } from '@storage/index';

package/src/templates/project/basic/src/index.ts.tpl

@@ -1,10 +1,53 @@
 /**
- * {{projectName}} - Zintrust Application Entry Point
+ * test-app - Zintrust Application Entry Point
  */
 
-import { Application, Server } from '@zintrust/core';
-import { Env } from '@config/env';
-import { Logger } from '@config/logger';
+import { Application, Env, Logger, Server } from '@zintrust/core';
+import process from '@zintrust/core/node';
+
+type AppInstance = ReturnType<typeof Application.create>;
+type ServerInstance = ReturnType<typeof Server.create>;
+
+function withTimeout<T>(promise: Promise<T>, ms: number, timeoutMessage = 'Shutdown timed out'): Promise<T> {
+  if (!Number.isFinite(ms) || ms <= 0) return promise;
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new globalThis.Error(timeoutMessage)), ms);
+  });
+
+  return Promise.race([promise, timeout]).finally(() => {
+    if (timer) clearTimeout(timer);
+  }) as Promise<T>;
+}
+
+async function stopServices(server: ServerInstance, app: AppInstance): Promise<void> {
+  await server.close();
+  await app.shutdown();
+}
+
+async function shutdownGracefully(signal: string, server: ServerInstance, app: AppInstance): Promise<void> {
+  Logger.info(`${signal} received, shutting down gracefully...`);
+
+  const timeoutMs = Env.getInt('SHUTDOWN_TIMEOUT', 1500);
+  const forceExitMs = Env.getInt('SHUTDOWN_FORCE_EXIT_MS', 2500);
+
+  const forceExitTimer = globalThis.setTimeout(() => {
+    process.exit(0);
+  }, forceExitMs);
+
+  (forceExitTimer as unknown as { unref?: () => void }).unref?.();
+
+  try {
+    await withTimeout(stopServices(server, app), timeoutMs);
+    globalThis.clearTimeout(forceExitTimer);
+    process.exit(0);
+  } catch (error) {
+    Logger.error('Graceful shutdown failed:', error);
+    process.exit(1);
+  }
+}
 
 /**
  * Start the application
@@ -29,43 +72,8 @@ async function start() {
 
     Logger.info(`Server running at http://${host}:${port}`);
 
-    const shutdown = async (signal: string): Promise<void> => {
-      Logger.info(`${signal} received, shutting down gracefully...`);
-
-      const timeoutMs = Env.getInt('SHUTDOWN_TIMEOUT', 10000);
-      const withTimeout = async <T>(promise: Promise<T>, ms: number): Promise<T> => {
-        if (ms <= 0) return promise;
-        return new Promise<T>((resolve, reject) => {
-          const timer = setTimeout(() => reject(new globalThis.Error('Shutdown timed out')), ms);
-          promise
-            .then((value) => {
-              clearTimeout(timer);
-              resolve(value);
-            })
-            .catch((err) => {
-              clearTimeout(timer);
-              reject(err);
-            });
-        });
-      };
-
-      try {
-        await withTimeout(
-          (async () => {
-            await server.close();
-            await app.shutdown();
-          })(),
-          timeoutMs
-        );
-        process.exit(0);
-      } catch (error) {
-        Logger.error('Graceful shutdown failed:', error);
-        process.exit(1);
-      }
-    };
-
-    process.on('SIGTERM', () => void shutdown('SIGTERM'));
-    process.on('SIGINT', () => void shutdown('SIGINT'));
+    process.on('SIGTERM', () => void shutdownGracefully('SIGTERM', server, app));
+    process.on('SIGINT', () => void shutdownGracefully('SIGINT', server, app));
   } catch (error) {
     Logger.error('Failed to start application:', error);
     process.exit(1);

package/src/templates/project/basic/template.json

@@ -2,10 +2,10 @@
   "name": "basic",
   "description": "Basic Zintrust project structure",
   "directories": [
+    "config",
     "app/Controllers",
     "app/Middleware",
     "app/Models",
-    "config",
     "database/migrations",
     "database/seeders",
     "logs",

package/src/templates/project/basic/tsconfig.json.tpl

@@ -13,6 +13,8 @@
       "@app/*": ["./app/*"],
       "@toolkit/*": ["./app/Toolkit/*"],
       "@config/*": ["./config/*"],
+      "@app/*": ["./app/*"],
+      "@toolkit/*": ["./app/Toolkit/*"],
       "@routes/*": ["./routes/*"],
       "@database/*": ["./database/*"],
 
@@ -29,6 +31,6 @@
       "@queue/*": ["./src/tools/queue/*"]
     }
   },
-  "include": ["src/**/*", "app/**/*", "routes/**/*", "database/**/*", "config/**/*"],
+  "include": ["src/**/*", "app/**/*", "routes/**/*", "database/**/*"],
   "exclude": ["node_modules", "dist"]
 }

package/src/toolkit/Secrets/EnvFile.js

@@ -1,6 +1,6 @@
-import { ErrorFactory } from '../../exceptions/ZintrustError';
-import { fsPromises as fs } from '../../node-singletons/fs';
-import * as path from '../../node-singletons/path';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import { fsPromises as fs } from '../../node-singletons/fs.js';
+import * as path from '../../node-singletons/path.js';
 const isValidKey = (key) => /^[A-Z0-9_]+$/.test(key);
 const parseEnvLine = (line) => {
     const trimmed = line.trim();

package/src/toolkit/Secrets/Manifest.js

@@ -1,6 +1,6 @@
-import { ErrorFactory } from '../../exceptions/ZintrustError';
-import { fsPromises as fs } from '../../node-singletons/fs';
-import * as path from '../../node-singletons/path';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import { fsPromises as fs } from '../../node-singletons/fs.js';
+import * as path from '../../node-singletons/path.js';
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 const assertString = (value, name) => {
     if (typeof value !== 'string' || value.trim() === '') {

package/src/toolkit/Secrets/index.js

@@ -4,11 +4,11 @@
  * Internal framework module intended for CLI usage.
  * It may use Node APIs (via node-singletons) and should not be used by runtime apps.
  */
-import { ErrorFactory } from '../../exceptions/ZintrustError';
-import { EnvFile } from '../Secrets/EnvFile';
-import { Manifest } from '../Secrets/Manifest';
-import { AwsSecretsManager } from '../Secrets/providers/AwsSecretsManager';
-import { CloudflareKv } from '../Secrets/providers/CloudflareKv';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import { EnvFile } from '../Secrets/EnvFile.js';
+import { Manifest } from '../Secrets/Manifest.js';
+import { AwsSecretsManager } from '../Secrets/providers/AwsSecretsManager.js';
+import { CloudflareKv } from '../Secrets/providers/CloudflareKv.js';
 const resolveProvider = (provider) => {
     if (provider === 'aws' || provider === 'cloudflare')
         return provider;

package/src/toolkit/Secrets/providers/AwsSecretsManager.js

@@ -1,5 +1,5 @@
-import { AwsSigV4 } from '../../../common/index';
-import { ErrorFactory } from '../../../exceptions/ZintrustError';
+import { AwsSigV4 } from '../../../common/index.js';
+import { ErrorFactory } from '../../../exceptions/ZintrustError.js';
 const sha256Hex = (data) => AwsSigV4.sha256Hex(data);
 const buildAuthorization = (params) => {
     const canonicalUri = '/';

package/src/toolkit/Secrets/providers/CloudflareKv.js

@@ -1,4 +1,4 @@
-import { ErrorFactory } from '../../../exceptions/ZintrustError';
+import { ErrorFactory } from '../../../exceptions/ZintrustError.js';
 export const CloudflareKv = Object.freeze({
     createFromEnv() {
         const accountId = process.env['CLOUDFLARE_ACCOUNT_ID'] ?? '';

package/src/tools/broadcast/Broadcast.js

@@ -1,9 +1,9 @@
-import { InMemoryDriver } from './drivers/InMemory';
-import { PusherDriver } from './drivers/Pusher';
-import { RedisDriver } from './drivers/Redis';
-import { RedisHttpsDriver } from './drivers/RedisHttps';
-import broadcastConfig from '../../config/broadcast';
-import { ErrorFactory } from '../../exceptions/ZintrustError';
+import { InMemoryDriver } from './drivers/InMemory.js';
+import { PusherDriver } from './drivers/Pusher.js';
+import { RedisDriver } from './drivers/Redis.js';
+import { RedisHttpsDriver } from './drivers/RedisHttps.js';
+import broadcastConfig from '../../config/broadcast.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
 export const Broadcast = Object.freeze({
     async send(channel, event, data) {
         const driver = broadcastConfig.getDriverName();

package/src/tools/broadcast/drivers/BaseDriver.js

@@ -1,4 +1,4 @@
-import { ErrorFactory } from '../../../exceptions/ZintrustError';
+import { ErrorFactory } from '../../../exceptions/ZintrustError.js';
 export const BaseDriver = Object.freeze({
     async send() {
         await Promise.resolve();

package/src/tools/broadcast/drivers/Pusher.d.ts

@@ -1,4 +1,4 @@
-import type { PusherBroadcastDriverConfig } from '../../../config/broadcast';
+import type { PusherBroadcastDriverConfig } from '../../../config/type';
 export declare const PusherDriver: Readonly<{
     send(config: PusherBroadcastDriverConfig, channel: string, event: string, data: unknown): Promise<{
         ok: boolean;

package/src/tools/broadcast/drivers/Pusher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Pusher.d.ts","sourceRoot":"","sources":["../../../../../src/tools/broadcast/drivers/Pusher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAqDrE,eAAO,MAAM,YAAY;iBACJ,2BAA2B,WAAW,MAAM,SAAS,MAAM,QAAQ,OAAO;;;EAkD7F,CAAC;AAEH,eAAe,YAAY,CAAC"}
+{"version":3,"file":"Pusher.d.ts","sourceRoot":"","sources":["../../../../../src/tools/broadcast/drivers/Pusher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAqDhE,eAAO,MAAM,YAAY;iBACJ,2BAA2B,WAAW,MAAM,SAAS,MAAM,QAAQ,OAAO;;;EAkD7F,CAAC;AAEH,eAAe,YAAY,CAAC"}