@bloomneo/appkit 1.2.9 → 1.5.2

package/examples/logger.ts

@@ -0,0 +1,41 @@
+/**
+ * CANONICAL PATTERN — structured logging with component tagging.
+ *
+ * Copy this file when you need logging. The pattern: get a component-tagged
+ * logger at module scope, then call .info() / .warn() / .error() with a
+ * message + meta object. Logs are structured JSON in production, pretty
+ * console output in development.
+ *
+ * Set BLOOM_LOGGER_FILE_PATH to also write to a file.
+ * Set BLOOM_LOGGER_HTTP_URL to ship to a centralized log collector.
+ * Same code works in all three modes.
+ */
+
+import { loggerClass } from '@bloomneo/appkit';
+
+// Component-tagged logger — use one per file or per logical area.
+const logger = loggerClass.get('users');
+
+export function exampleLogging() {
+  logger.debug('Lookup started', { userId: 42 });          // dev only
+  logger.info('User created', { userId: 42, email: 'a@b' });
+  logger.warn('Slow query', { ms: 3200, table: 'users' });
+  logger.error('Database connection lost', { host: 'db1' });
+  logger.fatal('OOM, exiting', { rss: process.memoryUsage().rss });
+}
+
+// ── Inside a route handler ──────────────────────────────────────────
+import { errorClass } from '@bloomneo/appkit';
+const error = errorClass.get();
+
+export const createUserRoute = error.asyncRoute(async (req, res) => {
+  logger.info('Creating user', { ip: req.ip, email: req.body.email });
+  try {
+    // ...create logic
+    logger.info('User created successfully', { userId: 123 });
+    res.json({ ok: true });
+  } catch (e) {
+    logger.error('User creation failed', { error: (e as Error).message });
+    throw e;
+  }
+});

package/examples/queue.ts

@@ -0,0 +1,58 @@
+/**
+ * CANONICAL PATTERN — background job queue with auto-scaling backend.
+ *
+ * Copy this file when you need background jobs. Default backend is in-process
+ * memory (good for dev). Set REDIS_URL to upgrade to distributed Redis.
+ *
+ * Same code works for all backends — no changes needed.
+ *
+ * queue.add(jobType, data, options)   — enqueue immediately or with a fixed delay
+ * queue.schedule(jobType, data, delayMs) — alias: enqueue with a delay in ms
+ * queue.process(jobType, handler)     — register a worker for that job type
+ *
+ * For cron-style recurring jobs: use a cron library (node-cron, etc.) to call
+ * queue.add() at the right interval — there is no built-in cron scheduler.
+ */
+
+import { queueClass, loggerClass, errorClass } from '@bloomneo/appkit';
+
+const queue = queueClass.get();
+const logger = loggerClass.get('queue');
+const error = errorClass.get();
+
+// ── Producer: enqueue jobs from a route ─────────────────────────────
+export const enqueueEmailRoute = error.asyncRoute(async (req, res) => {
+  const { to, subject, body } = req.body;
+
+  await queue.add(
+    'send-email',
+    { to, subject, body },
+    {
+      delay: 0,       // run immediately (ms)
+      attempts: 3,    // retry up to 3 times on failure (not "retries")
+      priority: 1,    // lower number = higher priority
+    },
+  );
+
+  res.json({ queued: true });
+});
+
+// ── Consumer: process jobs (run in a worker process or main app) ────
+queue.process('send-email', async (data) => {
+  const { to, subject, body } = data as { to: string; subject: string; body: string };
+  logger.info('Email sent', { to, subject });
+  return { sent: true };
+});
+
+// ── Delayed job (run once after N ms, not cron-style) ───────────────
+// To run cleanup every day at 03:00, use node-cron to call queue.add() at the
+// right time — queue.schedule() accepts a delay in milliseconds, not a cron expression.
+await queue.schedule(
+  'cleanup-expired-tokens',
+  {},
+  8 * 60 * 60 * 1000,   // run once, 8 hours from now
+);
+
+queue.process('cleanup-expired-tokens', async () => {
+  logger.info('Token cleanup ran');
+});

package/examples/security.ts

@@ -0,0 +1,46 @@
+/**
+ * CANONICAL PATTERN — rate limiting, CSRF, encryption, input sanitization.
+ *
+ * Copy this file when you need security middleware. AppKit's security module
+ * covers four common needs from one xxxClass.get() instance.
+ *
+ * Required env: BLOOM_SECURITY_CSRF_SECRET, BLOOM_SECURITY_ENCRYPTION_KEY
+ */
+
+import { securityClass, errorClass } from '@bloomneo/appkit';
+
+const security = securityClass.get();
+const error = errorClass.get();
+
+// ── Rate limiting middleware ────────────────────────────────────────
+// 100 requests per 15-minute window per IP
+export const apiRateLimit = security.requests(100, 15 * 60 * 1000);
+
+// 5 requests per minute (e.g. for a login endpoint)
+export const loginRateLimit = security.requests(5, 60 * 1000);
+
+// ── CSRF protection ─────────────────────────────────────────────────
+// security.forms() is a single middleware that handles BOTH:
+//   - Injecting a CSRF token into the response (GET requests)
+//   - Validating the token on state-changing requests (POST/PUT/DELETE)
+// Mount it once globally — no separate "require" middleware needed.
+export const csrfMiddleware = security.forms();
+
+// ── Encryption (AES-256-GCM) ────────────────────────────────────────
+export function encryptApiKey(plaintext: string): string {
+  return security.encrypt(plaintext);  // → opaque ciphertext string
+}
+
+export function decryptApiKey(ciphertext: string): string {
+  return security.decrypt(ciphertext);
+}
+
+// ── Input sanitization ──────────────────────────────────────────────
+// security.input() strips XSS payloads and control characters from free-form text.
+// For email/URL validation, use a dedicated validation library (e.g. zod, validator.js).
+export const submitRoute = error.asyncRoute(async (req, res) => {
+  const safeMessage = security.input(req.body.message);  // strip XSS
+  const safeHtml = security.html(req.body.bio);          // allow safe HTML tags only
+
+  res.json({ ok: true, sanitized: { message: safeMessage, bio: safeHtml } });
+});

package/examples/storage.ts

@@ -0,0 +1,44 @@
+/**
+ * CANONICAL PATTERN — file upload + retrieval with auto-scaling backend.
+ *
+ * Copy this file when you need to store files. The same code works against
+ * local disk (default), AWS S3 (set AWS_S3_BUCKET), or Cloudflare R2
+ * (set R2_BUCKET). No code changes needed — just .env.
+ */
+
+import { storageClass, errorClass, securityClass } from '@bloomneo/appkit';
+import type { Request, Response } from 'express';
+
+const storage = storageClass.get();
+const error = errorClass.get();
+const security = securityClass.get();
+
+// ── Upload (with rate limit + filename sanitization) ────────────────
+export const uploadRoute = [
+  security.requests(10, 60_000),  // max 10 uploads per minute per IP
+  error.asyncRoute(async (req: Request & { file: any }, res: Response) => {
+    if (!req.file) throw error.badRequest('File required (use multer middleware)');
+
+    // Sanitize the filename so a malicious user can't write to ../../../etc/...
+    const safeName = security.input(req.file.originalname);
+    const key = `uploads/${Date.now()}-${safeName}`;
+
+    await storage.put(key, req.file.buffer, {
+      contentType: req.file.mimetype,
+    });
+
+    res.json({
+      key,
+      url: storage.url(key),  // public URL (or signed URL for private buckets)
+    });
+  }),
+];
+
+// ── Download (signed URL — works with private S3 buckets) ───────────
+export const downloadRoute = error.asyncRoute(async (req, res) => {
+  const key = req.params.key;
+  if (!(await storage.exists(key))) throw error.notFound('File not found');
+
+  const signedUrl = await storage.signedUrl(key, 3600);  // valid for 1 hour
+  res.json({ url: signedUrl });
+});

package/examples/util.ts

@@ -0,0 +1,47 @@
+/**
+ * CANONICAL PATTERN — small zero-dependency utility helpers.
+ *
+ * Copy this file when you need any of the util methods. These are the
+ * common Node.js helpers that get reinvented in every project — appkit
+ * ships them once with consistent semantics.
+ *
+ * Public methods: get, isEmpty, slugify, chunk, debounce, pick,
+ *                 unique, clamp, formatBytes, truncate, sleep, uuid
+ */
+
+import { utilClass } from '@bloomneo/appkit';
+
+const util = utilClass.get();
+
+// ── Safe deep property access (read-only) ───────────────────────────
+const obj = { a: { b: { c: 42 } } };
+const value = util.get(obj, 'a.b.c', 0);              // → 42
+const missing = util.get(obj, 'a.b.x.y', 'default');  // → 'default' (safe)
+// Note: there is no util.set() — use plain assignment for mutation.
+
+// ── Subset ──────────────────────────────────────────────────────────
+const user = { id: 1, email: 'a@b', password: 'secret', role: 'admin' };
+const minimal = util.pick(user, ['id', 'email']);     // → { id, email }
+// Note: there is no util.omit() — use util.pick() with the keys you want to keep.
+
+// ── Array helpers ───────────────────────────────────────────────────
+const items = [1, 2, 3, 4, 5, 6, 7, 8, 9];
+const batches = util.chunk(items, 3);                 // → [[1,2,3], [4,5,6], [7,8,9]]
+const deduped = util.unique([1, 2, 2, 3, 3]);         // → [1, 2, 3]
+
+// ── Function helpers ────────────────────────────────────────────────
+const debouncedSearch = util.debounce((q: string) => {
+  // ...api call
+}, 300);
+// Note: there is no util.throttle() — use util.debounce() for rate-limiting calls.
+
+// ── Misc ────────────────────────────────────────────────────────────
+const id = util.uuid();                               // → 'a1b2c3d4-...'
+const slug = util.slugify('My Awesome Post!');        // → 'my-awesome-post'
+const size = util.formatBytes(1_572_864);             // → '1.5 MB'
+const clamped = util.clamp(150, 0, 100);              // → 100
+const short = util.truncate('A very long string', 10); // → 'A very lon...'
+
+await util.sleep(100);                                // → wait 100ms
+
+export { value, missing, minimal, batches, deduped, id, slug, size, clamped, short };