millas 0.2.12-beta → 0.2.12-beta-2

package/src/core/db.js

@@ -0,0 +1,9 @@
+const {
+    Model,
+    fields
+} = require("../orm");
+const { migrations } = require("../orm/migration/operations");
+
+module.exports = {
+    Model, fields,migrations
+}

package/src/core/foundation.js

@@ -0,0 +1,59 @@
+'use strict';
+
+// ── HTTP Layer ────────────────────────────────────────────────────
+const {
+  MillasRequest,
+  MillasResponse,
+  ResponseDispatcher,
+  jsonify,
+  view,
+  redirect,
+  text,
+  file,
+  empty,
+  abort,
+  notFound,
+  unauthorized,
+  forbidden,
+} = require('../http/index');
+const RequestContext = require('../http/RequestContext');
+
+// ── DI Container ─────────────────────────────────────────────────
+const Container          = require('../container/Container');
+const Application        = require('../container/Application');
+const ServiceProvider    = require('../providers/ServiceProvider');
+const ProviderRegistry   = require('../providers/ProviderRegistry');
+
+// ── Events ────────────────────────────────────────────────────────
+const EventEmitter         = require('../events/EventEmitter');
+const Event                = require('../events/Event');
+const Listener             = require('../events/Listener');
+const { emit }             = require('../events/EventEmitter');
+const EventServiceProvider = require('../providers/EventServiceProvider');
+
+// ── Cache ─────────────────────────────────────────────────────────
+const Cache        = require('../cache/Cache');
+const MemoryDriver = require('../cache/drivers/MemoryDriver');
+const FileDriver   = require('../cache/drivers/FileDriver');
+const NullDriver   = require('../cache/drivers/NullDriver');
+const { CacheServiceProvider, StorageServiceProvider } = require('../providers/CacheStorageServiceProvider');
+
+// ── Storage ───────────────────────────────────────────────────────
+const Storage     = require('../storage/Storage');
+const LocalDriver = require('../storage/drivers/LocalDriver');
+
+module.exports = {
+  // ── Millas HTTP layer ──────────────────────────────────────────
+  MillasRequest, MillasResponse, ResponseDispatcher, RequestContext,
+  jsonify, view, redirect, text, send_file:file, empty,
+  abort, notFound, unauthorized, forbidden,
+
+  // DI
+  Container, Application, ServiceProvider, ProviderRegistry,
+  // Events
+  EventEmitter, Event, Listener, emit, EventServiceProvider,
+  // Cache
+  Cache, MemoryDriver, FileDriver, NullDriver, CacheServiceProvider,
+  // Storage
+  Storage, LocalDriver, StorageServiceProvider,
+};

package/src/core/http.js

@@ -0,0 +1,11 @@
+const Controller = require("../controller/Controller");
+const Middleware = require("../middleware/Middleware");
+const MiddlewarePipeline = require("../middleware/MiddlewarePipeline");
+const CorsMiddleware = require("../middleware/CorsMiddleware");
+const ThrottleMiddleware = require("../middleware/ThrottleMiddleware");
+const LogMiddleware = require("../middleware/LogMiddleware");
+const HttpError = require("../errors/HttpError");
+module.exports = {
+    Controller, Middleware, MiddlewarePipeline,
+  CorsMiddleware, ThrottleMiddleware, LogMiddleware, HttpError,
+}

package/src/core/lang.js

@@ -0,0 +1 @@
+module.exports = require('../i18n')

package/src/core/mail.js

@@ -0,0 +1,6 @@
+const {MailMessage, TemplateEngine, SmtpDriver, SendGridDriver, MailgunDriver, LogDriver} = require("../mail");
+const MailServiceProvider = require("../providers/MailServiceProvider");
+module.exports = {
+    MailMessage, TemplateEngine,
+    SmtpDriver, SendGridDriver, MailgunDriver, MailServiceProvider,
+}

package/src/core/queue.js

@@ -0,0 +1,7 @@
+const Job = require("../queue/Job");
+const QueueWorker = require("../queue/workers/QueueWorker");
+const {dispatch} = require("../queue/Queue");
+const QueueServiceProvider = require("../providers/QueueServiceProvider");
+module.exports = {
+    Job, QueueWorker, dispatch, QueueServiceProvider,
+}

package/src/core/validation.js

@@ -0,0 +1,29 @@
+const {
+    Validator,
+    BaseValidator,
+    StringValidator,
+    EmailValidator,
+    NumberValidator,
+    BooleanValidator,
+    DateValidator,
+    ArrayValidator,
+    ObjectValidator,
+    FileValidator,
+    string,
+    email,
+    number,
+    boolean,
+    date,
+    array,
+    objectField,
+    fileField
+} = require("../validation/Validator");
+module.exports = {
+    Validator,
+    BaseValidator,
+    StringValidator, EmailValidator, NumberValidator, BooleanValidator,
+    DateValidator, ArrayValidator, ObjectValidator, FileValidator,
+    string, email, number, boolean, date, array,
+    object: objectField,
+    file: fileField,
+}

package/src/facades/Admin.js

@@ -34,7 +34,7 @@
  *   Admin.register(PostResource);
  */
 
-const { Admin, AdminResource, AdminField, AdminFilter, AdminServiceProvider } = require('../index');
+const { Admin, AdminResource, AdminField, AdminFilter, AdminServiceProvider } = require('../core');
 
 let AdminInline;
 try { AdminInline = require('../admin/resources/AdminResource').AdminInline; } catch {}

package/src/facades/Auth.js

@@ -1,46 +1,29 @@
 'use strict';
 
+const { createFacade } = require('./Facade');
+const { AuthUser, Hasher, JwtDriver, AuthMiddleware, RoleMiddleware, AuthController, AuthServiceProvider } = require('../core');
+
 /**
- * millas/facades/Auth
- *
- * Authentication, JWT, and access control.
- *
- *   const { Auth, Hasher } = require('millas/facades/Auth');
- *
- *   // Hash a password
- *   const hash = await Hasher.make('secret123');
+ * Auth facade.
  *
- *   // Login
- *   const { user, token } = await Auth.login(email, password);
+ * @class
+ * @property {function(object): Promise<object>}                             register
+ * @property {function(string, string): Promise<{user, token, refreshToken}>} login
+ * @property {function(string): object}                                      verify
+ * @property {function(object): Promise<object|null>}                        user
+ * @property {function(object): Promise<object>}                             userOrFail
+ * @property {function(string, string): Promise<boolean>}                    checkPassword
+ * @property {function(string): Promise<string>}                             hashPassword
+ * @property {function(object, object=): string}                             issueToken
+ * @property {function(string): object}                                      decode
+ * @property {function(object): string}                                      generateResetToken
+ * @property {function(string): object}                                      verifyResetToken
+ * @property {function(function): void}                                      setUserModel
+ * @property {function(object): void}                                        swap
+ * @property {function(): void}                                              restore
  *
- *   // 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']));
+ * @see src/auth/Auth.js
  */
+class Auth extends createFacade('auth') {}
 
-const {
-  Auth,
-  Hasher,
-  JwtDriver,
-  AuthMiddleware,
-  RoleMiddleware,
-  AuthController,
-  AuthServiceProvider,
-} = require('../index');
-
-module.exports = {
-  Auth,
-  Hasher,
-  JwtDriver,
-  AuthMiddleware,
-  RoleMiddleware,
-  AuthController,
-  AuthServiceProvider,
-};
+module.exports = { Auth, AuthUser, Hasher, JwtDriver, AuthMiddleware, RoleMiddleware, AuthController, AuthServiceProvider };

package/src/facades/Cache.js

@@ -1,17 +1,28 @@
 'use strict';
 
+const {createFacade} = require('./Facade');
+
 /**
- * millas/facades/Cache
+ * Cache facade.
  *
- *   const { Cache } = require('millas/facades/Cache');
+ * @class
+ * @property {function(string, *, number=): Promise<void>}    set
+ * @property {function(string, *=): Promise<*>}               get
+ * @property {function(string): Promise<void>}                delete
+ * @property {function(string): Promise<void>}                deletePattern
+ * @property {function(): Promise<void>}                      flush
+ * @property {function(string, number, function): Promise<*>} remember
+ * @property {function(string, number=): Promise<number>}     increment
+ * @property {function(string, number=): Promise<number>}     decrement
+ * @property {function(string[]): Promise<object>}            getMany
+ * @property {function(object, number=): Promise<void>}       setMany
+ * @property {function(...string): TaggedCache}               tags
+ * @property {function(object): void}                         swap
+ * @property {function(): void}                               restore
  *
- *   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();
+ * @see src/cache/Cache.js
  */
+class Cache extends createFacade('cache') {
+}
 
-const { Cache, MemoryDriver, FileDriver, NullDriver, CacheServiceProvider } = require('../index');
-
-module.exports = { Cache, MemoryDriver, FileDriver, NullDriver, CacheServiceProvider };
+module.exports = Cache;

package/src/facades/Database.js

@@ -29,7 +29,7 @@ const {
   MigrationRunner,
   ModelInspector,
   DatabaseServiceProvider,
-} = require('../index');
+} = require('../core');
 
 module.exports = {
   Model,

package/src/facades/Events.js

@@ -1,24 +1,25 @@
 'use strict';
 
+const { createFacade } = require('./Facade');
+
 /**
- * millas/facades/Events
- *
- *   const { EventEmitter, emit } = require('millas/facades/Events');
+ * Events facade.
  *
- *   // Listen
- *   EventEmitter.on('user.created', async (event) => {
- *     await Mail.to(event.user.email).subject('Welcome').send();
- *   });
+ * @class
+ * @property {function(string|function, function[]|function): EventEmitter} listen
+ * @property {function(string|function, function): EventEmitter}            on
+ * @property {function(string|function, function): EventEmitter}            once
+ * @property {function(string|function, function): EventEmitter}            off
+ * @property {function(string, function): EventEmitter}                     onWildcard
+ * @property {function(string|Event, object=): Promise<void>}               emit
+ * @property {function(string|function): function[]}                        getListeners
+ * @property {function(string|function): EventEmitter}                      removeAll
+ * @property {function(): EventEmitter}                                      flush
+ * @property {function(object): void}                                        swap
+ * @property {function(): void}                                              restore
  *
- *   // Emit
- *   await emit('user.created', { user });
- *
- *   // Wildcard
- *   EventEmitter.onWildcard('user.*', async (event) => {
- *     Log.i('Events', event._name, event);
- *   });
+ * @see src/events/EventEmitter.js
  */
+class Events extends createFacade('events') {}
 
-const { EventEmitter, Event, Listener, emit, EventServiceProvider } = require('../index');
-
-module.exports = { EventEmitter, Event, Listener, emit, EventServiceProvider };
+module.exports = Events;

package/src/facades/Facade.js

@@ -0,0 +1,197 @@
+'use strict';
+
+/**
+ * Facade
+ *
+ * Base class for all Millas facades.
+ *
+ * A facade is a static proxy to a service that lives in the DI container.
+ * Instead of importing the service directly, developers use the facade and
+ * the framework resolves the correct instance transparently.
+ *
+ * ── How it works ─────────────────────────────────────────────────────────────
+ *
+ *   class Cache extends Facade {
+ *     static get facadeAccessor() { return 'cache'; }
+ *   }
+ *
+ *   Cache.get('key')
+ *   // ↓ Facade.__get intercepts 'get'
+ *   // ↓ container.make('cache')  → the Cache singleton
+ *   // ↓ singleton.get('key')
+ *
+ * ── Benefits over direct singleton re-export ─────────────────────────────────
+ *
+ *   1. Swappable — rebind 'cache' in the container and every call site
+ *      automatically uses the new implementation, zero changes.
+ *
+ *   2. Testable — swap the binding to a mock/fake in tests:
+ *        Facade.swap('cache', fakeCacheInstance);
+ *
+ *   3. Lazy — the service is only resolved from the container on first call,
+ *      not at require() time. Safe to import facades before boot.
+ *
+ *   4. Consistent — all services have the same access pattern regardless of
+ *      how they were registered (singleton, instance, factory).
+ *
+ * ── Usage ────────────────────────────────────────────────────────────────────
+ *
+ *   const { Cache } = require('millas/facades/Cache');
+ *
+ *   await Cache.get('user:1');
+ *   await Cache.set('user:1', user, 300);
+ *   await Cache.remember('stats', 60, () => Stats.compute());
+ */
+class Facade {
+  /**
+   * The container key this facade resolves to.
+   * Every subclass must override this.
+   *
+   * @returns {string}
+   */
+  static get facadeAccessor() {
+    throw new Error(
+      `Facade "${this.name}" must define a static facadeAccessor getter.\n` +
+      `  static get facadeAccessor() { return 'myService'; }`
+    );
+  }
+
+  // ── Container binding ──────────────────────────────────────────────────────
+
+  /**
+   * The shared container instance.
+   * Set by AppInitialiser once the container is fully booted.
+   * All facades share a single reference.
+   */
+  static _container = null;
+
+  /**
+   * Per-facade instance overrides — used by swap() for testing.
+   * key: facadeAccessor string → value: override instance
+   */
+  static _overrides = new Map();
+
+  /**
+   * Called by AppInitialiser after the container is booted.
+   * Wires all facades to the live container in one call.
+   *
+   * @param {import('../container/Container')} container
+   */
+  static setContainer(container) {
+    Facade._container = container;
+  }
+
+  /**
+   * Resolve the underlying service instance.
+   * Uses the override if one has been swapped in (for testing).
+   *
+   * @returns {object}
+   */
+  static _resolveInstance() {
+    const accessor = this.facadeAccessor;
+
+    if (Facade._overrides.has(accessor)) {
+      return Facade._overrides.get(accessor);
+    }
+
+    if (!Facade._container) {
+      throw new Error(
+        `[Millas] Facade "${this.name}" used before the application was booted.\n` +
+        `The container is not yet available. ` +
+        `Make sure you're not calling facade methods at module load time ` +
+        `(outside of route handlers, controllers, or provider boot methods).`
+      );
+    }
+
+    return Facade._container.make(accessor);
+  }
+
+  // ── Testing helpers ────────────────────────────────────────────────────────
+
+  /**
+   * Swap the facade's underlying instance for testing.
+   * The swap is scoped to the accessor key so it only affects this facade.
+   *
+   *   Cache.swap({ get: async () => 'mocked' });
+   *   const val = await Cache.get('key');  // → 'mocked'
+   *   Cache.restore();
+   *
+   * @param {object} instance
+   */
+  static swap(instance) {
+    Facade._overrides.set(this.facadeAccessor, instance);
+  }
+
+  /**
+   * Remove a test swap and return to the real container binding.
+   */
+  static restore() {
+    Facade._overrides.delete(this.facadeAccessor);
+  }
+
+  /**
+   * Remove all test swaps.
+   */
+  static restoreAll() {
+    Facade._overrides.clear();
+  }
+}
+
+// ── Proxy handler ─────────────────────────────────────────────────────────────
+//
+// Intercepts every static property access on a Facade subclass.
+// If the property isn't a real static member of the class, it's assumed
+// to be a method or property on the underlying service instance.
+//
+// This means Cache.get → resolves the 'cache' service → calls .get on it.
+// It also means Cache.set, Cache.remember, Cache.tags, etc. all work
+// without listing them explicitly.
+
+const FACADE_OWN_PROPS = new Set([
+  'facadeAccessor',
+  '_container',
+  '_overrides',
+  'setContainer',
+  '_resolveInstance',
+  'swap',
+  'restore',
+  'restoreAll',
+  'name',
+  'prototype',
+  'length',
+]);
+
+const FacadeProxyHandler = {
+  get(target, prop, receiver) {
+    // Let real static members through untouched
+    if (FACADE_OWN_PROPS.has(prop) || prop in target) {
+      return Reflect.get(target, prop, receiver);
+    }
+
+    // Symbol access (Symbol.toPrimitive, Symbol.iterator, etc.) — pass through
+    if (typeof prop === 'symbol') {
+      return Reflect.get(target, prop, receiver);
+    }
+
+    // Proxy the call to the resolved service instance
+    return (...args) => target._resolveInstance()[prop](...args);
+  },
+};
+
+/**
+ * Create a Facade subclass that is automatically wrapped in a Proxy.
+ * Used internally — subclasses extend this instead of Facade directly.
+ *
+ * @example
+ * class Cache extends createFacade('cache') {}
+ */
+function createFacade(accessor) {
+  class BoundFacade extends Facade {
+    static get facadeAccessor() { return accessor; }
+  }
+  return new Proxy(BoundFacade, FacadeProxyHandler);
+}
+
+module.exports = Facade;
+module.exports.createFacade = createFacade;
+module.exports.FacadeProxyHandler = FacadeProxyHandler;

package/src/facades/Http.js

@@ -1,54 +1,51 @@
 'use strict';
 
+const { createFacade } = require('./Facade');
+// const {PendingRequest,HttpResponse} = require('../http/HttpClient');
+
 /**
- * millas/facades/Http
+ * Fluent outbound HTTP client facade.
+ * Resolved from the DI container — every method creates a fresh PendingRequest.
+ *
+ * @class
  *
- * Response builders and HTTP helpers.
- * These are the primary tools for returning responses from route handlers.
+ * — Verbs
+ * @property {function(string, object=): Promise<HttpResponse>} get
+ * @property {function(string, object=): Promise<HttpResponse>} post
+ * @property {function(string, object=): Promise<HttpResponse>} put
+ * @property {function(string, object=): Promise<HttpResponse>} patch
+ * @property {function(string, object=): Promise<HttpResponse>} delete
+ * @property {function(string, object=): Promise<HttpResponse>} head
+ * @property {function(string): Promise<HttpResponse>}          options
  *
- *   const { jsonify, redirect, abort } = require('millas/facades/Http');
+ * — Builder (each returns PendingRequest for chaining)
+ * @property {function(string): PendingRequest}             baseUrl
+ * @property {function(object): PendingRequest}             withHeaders
+ * @property {function(string, string=): PendingRequest}    withToken
+ * @property {function(string, string): PendingRequest}     withBasicAuth
+ * @property {function(object): PendingRequest}             withCookies
+ * @property {function(string): PendingRequest}             withUserAgent
+ * @property {function(string, string=): PendingRequest}    withBody
+ * @property {function(string): PendingRequest}             accept
+ * @property {function(): PendingRequest}                   acceptJson
+ * @property {function(): PendingRequest}                   asJson
+ * @property {function(): PendingRequest}                   asForm
+ * @property {function(): PendingRequest}                   asMultipart
+ * @property {function(number): PendingRequest}             timeout
+ * @property {function(number, number=): PendingRequest}    retry
+ * @property {function(): PendingRequest}                   throwOnFailure
+ * @property {function(function): PendingRequest}           beforeSending
+ * @property {function(function): PendingRequest}           afterReceiving
  *
- *   Route.get('/users', async ({ query }) => {
- *     const users = await User.all();
- *     return jsonify(users);
- *   });
+ * — Concurrent
+ * @property {function(function): Promise<HttpResponse[]>}  pool
  *
- *   Route.post('/users', async ({ body }) => {
- *     const user = await User.create(body);
- *     return jsonify(user, { status: 201 });
- *   });
+ * — Testing
+ * @property {function(object): void} swap
+ * @property {function(): void}       restore
+ *
+ * @see src/http/HttpClient.js
  */
+class Http extends createFacade('http') {}
 
-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,
-};
+module.exports = Http;