millas 0.2.11 → 0.2.12-beta

package/src/facades/Auth.js

@@ -0,0 +1,46 @@
+'use strict';
+
+/**
+ * millas/facades/Auth
+ *
+ * Authentication, JWT, and access control.
+ *
+ *   const { Auth, Hasher } = require('millas/facades/Auth');
+ *
+ *   // Hash a password
+ *   const hash = await Hasher.make('secret123');
+ *
+ *   // Login
+ *   const { user, token } = await Auth.login(email, password);
+ *
+ *   // Verify JWT
+ *   const payload = Auth.verify(token);
+ *
+ *   // Protect routes
+ *   Route.prefix('/api').middleware(['auth']).group(() => {
+ *     Route.get('/me', ({ user }) => jsonify(user));
+ *   });
+ *
+ *   // Role-based access
+ *   middlewareRegistry.register('admin', new RoleMiddleware(['admin']));
+ */
+
+const {
+  Auth,
+  Hasher,
+  JwtDriver,
+  AuthMiddleware,
+  RoleMiddleware,
+  AuthController,
+  AuthServiceProvider,
+} = require('../index');
+
+module.exports = {
+  Auth,
+  Hasher,
+  JwtDriver,
+  AuthMiddleware,
+  RoleMiddleware,
+  AuthController,
+  AuthServiceProvider,
+};

package/src/facades/Cache.js

@@ -0,0 +1,17 @@
+'use strict';
+
+/**
+ * millas/facades/Cache
+ *
+ *   const { Cache } = require('millas/facades/Cache');
+ *
+ *   await Cache.put('key', value, 300);         // 300 second TTL
+ *   const val = await Cache.get('key');
+ *   const val = await Cache.remember('key', 300, () => expensive());
+ *   await Cache.forget('key');
+ *   await Cache.flush();
+ */
+
+const { Cache, MemoryDriver, FileDriver, NullDriver, CacheServiceProvider } = require('../index');
+
+module.exports = { Cache, MemoryDriver, FileDriver, NullDriver, CacheServiceProvider };

package/src/facades/Database.js

@@ -0,0 +1,43 @@
+'use strict';
+
+/**
+ * millas/facades/Database
+ *
+ * ORM models, field definitions, and query builder.
+ *
+ *   const { Model, fields } = require('millas/facades/Database');
+ *
+ *   class Post extends Model {
+ *     static table = 'posts';
+ *     static fields = {
+ *       id:         fields.id(),
+ *       title:      fields.string({ max: 255 }),
+ *       author:     fields.ForeignKey('User', { relatedName: 'posts' }),
+ *       published:  fields.boolean({ default: false }),
+ *       created_at: fields.timestamp(),
+ *       updated_at: fields.timestamp(),
+ *     };
+ *   }
+ */
+
+const {
+  Model,
+  fields,
+  QueryBuilder,
+  DatabaseManager,
+  SchemaBuilder,
+  MigrationRunner,
+  ModelInspector,
+  DatabaseServiceProvider,
+} = require('../index');
+
+module.exports = {
+  Model,
+  fields,
+  QueryBuilder,
+  DatabaseManager,
+  SchemaBuilder,
+  MigrationRunner,
+  ModelInspector,
+  DatabaseServiceProvider,
+};

package/src/facades/Events.js

@@ -0,0 +1,24 @@
+'use strict';
+
+/**
+ * millas/facades/Events
+ *
+ *   const { EventEmitter, emit } = require('millas/facades/Events');
+ *
+ *   // Listen
+ *   EventEmitter.on('user.created', async (event) => {
+ *     await Mail.to(event.user.email).subject('Welcome').send();
+ *   });
+ *
+ *   // Emit
+ *   await emit('user.created', { user });
+ *
+ *   // Wildcard
+ *   EventEmitter.onWildcard('user.*', async (event) => {
+ *     Log.i('Events', event._name, event);
+ *   });
+ */
+
+const { EventEmitter, Event, Listener, emit, EventServiceProvider } = require('../index');
+
+module.exports = { EventEmitter, Event, Listener, emit, EventServiceProvider };

package/src/facades/Http.js

@@ -0,0 +1,54 @@
+'use strict';
+
+/**
+ * millas/facades/Http
+ *
+ * Response builders and HTTP helpers.
+ * These are the primary tools for returning responses from route handlers.
+ *
+ *   const { jsonify, redirect, abort } = require('millas/facades/Http');
+ *
+ *   Route.get('/users', async ({ query }) => {
+ *     const users = await User.all();
+ *     return jsonify(users);
+ *   });
+ *
+ *   Route.post('/users', async ({ body }) => {
+ *     const user = await User.create(body);
+ *     return jsonify(user, { status: 201 });
+ *   });
+ */
+
+const {
+  MillasRequest,
+  MillasResponse,
+  ResponseDispatcher,
+  RequestContext,
+  jsonify,
+  view,
+  redirect,
+  text,
+  file,
+  empty,
+  abort,
+  notFound,
+  unauthorized,
+  forbidden,
+} = require('../index');
+
+module.exports = {
+  MillasRequest,
+  MillasResponse,
+  ResponseDispatcher,
+  RequestContext,
+  jsonify,
+  view,
+  redirect,
+  text,
+  send_file:file,
+  empty,
+  abort,
+  notFound,
+  unauthorized,
+  forbidden,
+};

package/src/facades/Log.js

@@ -0,0 +1,56 @@
+'use strict';
+
+/**
+ * millas/facades/Log
+ *
+ * Application and internal logging.
+ *
+ *   const { Log, LEVELS } = require('millas/facades/Log');
+ *
+ *   Log.i('Server started');
+ *   Log.tag('UserService').d('Fetching user', { id: 5 });
+ *   Log.w('Auth', 'Token expiring soon', { userId: 5 });
+ *   Log.e('Payment', 'Stripe failed', error);
+ *   Log.wtf('This should never happen');
+ *
+ *   // Timer
+ *   const done = Log.time('DB query');
+ *   const rows = await db.select();
+ *   done(); // → D  Timer  DB query: 42ms
+ *
+ *   // Timed async
+ *   const users = await Log.timed('fetchUsers', () => User.all());
+ */
+
+const {
+  Log,
+  Logger,
+  LEVELS,
+  LEVEL_NAMES,
+  PrettyFormatter,
+  JsonFormatter,
+  SimpleFormatter,
+  ConsoleChannel,
+  FileChannel,
+  NullChannel,
+  StackChannel,
+  LogServiceProvider,
+} = require('../index');
+
+const MillasLog = require('../logger/internal');
+
+module.exports = {
+  Log,
+  MillasLog,
+  Logger,
+  LEVELS,
+  LEVEL_NAMES,
+  PrettyFormatter,
+  JsonFormatter,
+  SimpleFormatter,
+  ConsoleChannel,
+  FileChannel,
+  NullChannel,
+  StackChannel,
+  LogServiceProvider,
+};

package/src/facades/Mail.js

@@ -0,0 +1,40 @@
+'use strict';
+
+/**
+ * millas/facades/Mail
+ *
+ *   const { Mail, MailMessage } = require('millas/facades/Mail');
+ *
+ *   await Mail.to('alice@example.com')
+ *     .subject('Welcome!')
+ *     .html('<h1>Hi Alice</h1>')
+ *     .send();
+ *
+ *   // Template
+ *   await Mail.to(user.email)
+ *     .subject('Reset your password')
+ *     .view('emails/reset', { token, user })
+ *     .send();
+ */
+
+const {
+  Mail,
+  MailMessage,
+  TemplateEngine,
+  SmtpDriver,
+  SendGridDriver,
+  MailgunDriver,
+  LogDriver,
+  MailServiceProvider,
+} = require('../index');
+
+module.exports = {
+  Mail,
+  MailMessage,
+  TemplateEngine,
+  SmtpDriver,
+  SendGridDriver,
+  MailgunDriver,
+  LogDriver,
+  MailServiceProvider,
+};

package/src/facades/Queue.js

@@ -0,0 +1,23 @@
+'use strict';
+
+/**
+ * millas/facades/Queue
+ *
+ *   const { Queue, Job, dispatch } = require('millas/facades/Queue');
+ *
+ *   class SendWelcomeEmail extends Job {
+ *     async handle() {
+ *       await Mail.to(this.data.email).subject('Welcome').send();
+ *     }
+ *   }
+ *
+ *   // Dispatch a job
+ *   await dispatch(new SendWelcomeEmail({ email: user.email }));
+ *
+ *   // With delay
+ *   await dispatch(new SendWelcomeEmail({ email }), { delay: 60 });
+ */
+
+const { Queue, Job, QueueWorker, dispatch, QueueServiceProvider } = require('../index');
+
+module.exports = { Queue, Job, QueueWorker, dispatch, QueueServiceProvider };

package/src/facades/Storage.js

@@ -0,0 +1,17 @@
+'use strict';
+
+/**
+ * millas/facades/Storage
+ *
+ *   const { Storage } = require('millas/facades/Storage');
+ *
+ *   await Storage.put('avatars/user-5.jpg', fileBuffer);
+ *   const url  = await Storage.url('avatars/user-5.jpg');
+ *   const data = await Storage.get('avatars/user-5.jpg');
+ *   await Storage.delete('avatars/user-5.jpg');
+ *   const exists = await Storage.exists('avatars/user-5.jpg');
+ */
+
+const { Storage, LocalDriver, StorageServiceProvider } = require('../index');
+
+module.exports = { Storage, LocalDriver, StorageServiceProvider };

package/src/facades/Validation.js

@@ -0,0 +1,69 @@
+'use strict';
+
+/**
+ * millas/facades/Validation
+ *
+ * Field validators and schema runner.
+ *
+ *   const { string, email, number, boolean, date, array, object, file, Validator }
+ *     = require('millas/facades/Validation');
+ *
+ *   Route.post('/register', async ({ body }) => {
+ *     const data = await body.validate({
+ *       name:     string('Must be text').required('Name is required').min(2).max(100),
+ *       email:    email().required(),
+ *       age:      number().optional().min(0).max(120),
+ *       password: string().required().min(8).confirmed(),
+ *       role:     string().oneOf(['admin','user']).default('user'),
+ *       tags:     array().of(string().required()).optional(),
+ *       address:  object({
+ *         city:   string().required(),
+ *         zip:    string().matches(/^\d{5}$/, 'Invalid ZIP'),
+ *       }).optional(),
+ *       avatar:   file().optional().image().maxSize('2mb'),
+ *     });
+ *     return jsonify(await User.create(data), { status: 201 });
+ *   });
+ */
+
+const {
+  Validator,
+  BaseValidator,
+  StringValidator,
+  EmailValidator,
+  NumberValidator,
+  BooleanValidator,
+  DateValidator,
+  ArrayValidator,
+  ObjectValidator,
+  FileValidator,
+  string,
+  email,
+  number,
+  boolean,
+  date,
+  array,
+} = require('../index');
+
+const { object, file } = require('../validation/Validator');
+
+module.exports = {
+  Validator,
+  BaseValidator,
+  StringValidator,
+  EmailValidator,
+  NumberValidator,
+  BooleanValidator,
+  DateValidator,
+  ArrayValidator,
+  ObjectValidator,
+  FileValidator,
+  string,
+  email,
+  number,
+  boolean,
+  date,
+  array,
+  object,
+  file,
+};

package/src/http/MillasRequest.js

@@ -0,0 +1,253 @@
+'use strict';
+
+/**
+ * MillasRequest
+ *
+ * Wraps an Express request and exposes a clean, framework-level API.
+ * Developers never touch the raw Express req — they use this instead.
+ *
+ * The raw Express req is accessible via req.raw for escape hatches,
+ * but should never be needed in normal application code.
+ *
+ * Usage in route handlers:
+ *   Route.get('/users/:id', async (req) => {
+ *     const id   = req.param('id');
+ *     const page = req.input('page', 1);
+ *     const user = await User.findOrFail(id);
+ *     return jsonify(user);
+ *   });
+ */
+class MillasRequest {
+  /**
+   * @param {import('express').Request} expressReq
+   */
+  constructor(expressReq) {
+    /** @private — access via req.raw if absolutely necessary */
+    this._req = expressReq;
+
+    // Proxy commonly-used scalar properties for convenience
+    this.method  = expressReq.method;
+    this.path    = expressReq.path;
+    this.url     = expressReq.url;
+    this.baseUrl = expressReq.baseUrl;
+    this.originalUrl = expressReq.originalUrl;
+  }
+
+  // ─── Input ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Read a value from body, query, or route params — in that priority order.
+   * Returns defaultValue if not present.
+   *
+   *   req.input('email')
+   *   req.input('page', 1)
+   */
+  input(key, defaultValue = null) {
+    if (key === undefined) return this.all();
+    const r = this._req;
+    const v =
+      (r.body   && r.body[key]   !== undefined ? r.body[key]   : undefined) ??
+      (r.query  && r.query[key]  !== undefined ? r.query[key]  : undefined) ??
+      (r.params && r.params[key] !== undefined ? r.params[key] : undefined);
+    return v !== undefined ? v : defaultValue;
+  }
+
+  /**
+   * Read a route parameter.
+   *   req.param('id')
+   */
+  param(key, defaultValue = null) {
+    return this._req.params?.[key] ?? defaultValue;
+  }
+
+  /**
+   * Read a query string value.
+   *   req.query('page', 1)
+   */
+  query(key, defaultValue = null) {
+    if (key === undefined) return this._req.query || {};
+    return this._req.query?.[key] ?? defaultValue;
+  }
+
+  /**
+   * Read from the request body only.
+   *   req.body('email')
+   */
+  body(key, defaultValue = null) {
+    if (key === undefined) return this._req.body || {};
+    return this._req.body?.[key] ?? defaultValue;
+  }
+
+  /**
+   * Merge body + query + params into one flat object.
+   */
+  all() {
+    return {
+      ...this._req.params,
+      ...this._req.query,
+      ...this._req.body,
+    };
+  }
+
+  /**
+   * Return only the specified keys from the merged input.
+   *   req.only(['name', 'email'])
+   */
+  only(keys = []) {
+    const all = this.all();
+    return keys.reduce((acc, k) => {
+      if (k in all) acc[k] = all[k];
+      return acc;
+    }, {});
+  }
+
+  /**
+   * Return all input except the specified keys.
+   *   req.except(['password', 'token'])
+   */
+  except(keys = []) {
+    const all = this.all();
+    return Object.fromEntries(
+      Object.entries(all).filter(([k]) => !keys.includes(k))
+    );
+  }
+
+  // ─── Headers ────────────────────────────────────────────────────────────────
+
+  /**
+   * Read a request header (case-insensitive).
+   *   req.header('Authorization')
+   *   req.header('content-type')
+   */
+  header(name, defaultValue = null) {
+    if (name === undefined) return this._req.headers || {};
+    return this._req.headers?.[name.toLowerCase()] ?? defaultValue;
+  }
+
+  /**
+   * All request headers as a plain object.
+   */
+  get headers() {
+    return this._req.headers || {};
+  }
+
+  // ─── Cookies ────────────────────────────────────────────────────────────────
+
+  /**
+   * Read a cookie value.
+   *   req.cookie('session_id')
+   */
+  cookie(name, defaultValue = null) {
+    return this._req.cookies?.[name] ?? defaultValue;
+  }
+
+  // ─── Files ──────────────────────────────────────────────────────────────────
+
+  /**
+   * Get an uploaded file (requires multer or similar middleware upstream).
+   *   req.file('avatar')
+   */
+  file(name) {
+    if (this._req.files && this._req.files[name]) return this._req.files[name];
+    if (this._req.file  && this._req.file.fieldname === name) return this._req.file;
+    return null;
+  }
+
+  /**
+   * All uploaded files.
+   */
+  get files() {
+    return this._req.files || {};
+  }
+
+  // ─── User ───────────────────────────────────────────────────────────────────
+
+  /**
+   * The authenticated user (set by AuthMiddleware).
+   */
+  get user() {
+    return this._req.user ?? null;
+  }
+
+  /** Set the authenticated user (used by AuthMiddleware). */
+  set user(value) {
+    this._req.user = value;
+  }
+
+  // ─── Content negotiation ────────────────────────────────────────────────────
+
+  /**
+   * Returns true if the request expects a JSON response.
+   */
+  wantsJson() {
+    const accept = this.header('accept', '');
+    return accept.includes('application/json') || accept.includes('*/*');
+  }
+
+  /**
+   * Returns true if the request body is JSON.
+   */
+  isJson() {
+    const ct = this.header('content-type', '');
+    return ct.includes('application/json');
+  }
+
+  /**
+   * Returns true if this was an XMLHttpRequest / fetch call.
+   */
+  isAjax() {
+    return this.header('x-requested-with', '').toLowerCase() === 'xmlhttprequest';
+  }
+
+  // ─── Network ────────────────────────────────────────────────────────────────
+
+  /**
+   * Client IP address.
+   */
+  get ip() {
+    return this._req.ip || this._req.connection?.remoteAddress || null;
+  }
+
+  /**
+   * Request hostname (from Host header).
+   */
+  get hostname() {
+    return this._req.hostname || '';
+  }
+
+  /**
+   * Whether the request is HTTPS.
+   */
+  get secure() {
+    return this._req.secure || false;
+  }
+
+  // ─── Validation ─────────────────────────────────────────────────────────────
+
+  /**
+   * Validate request input against rules. Throws 422 HttpError on failure.
+   * Returns the validated data on success.
+   *
+   *   const data = await req.validate({
+   *     name:  'required|string|min:2|max:100',
+   *     email: 'required|email',
+   *     age:   'optional|number|min:0',
+   *   });
+   */
+  async validate(rules) {
+    const { Validator } = require('../validation/Validator');
+    return Validator.validate(this.all(), rules);
+  }
+
+  // ─── Escape hatch ────────────────────────────────────────────────────────────
+
+  /**
+   * The raw underlying Express request.
+   * Only use this when you genuinely need something MillasRequest doesn't expose.
+   */
+  get raw() {
+    return this._req;
+  }
+}
+
+module.exports = MillasRequest;