millas 0.2.11 → 0.2.12-beta-1

package/src/facades/Auth.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const { createFacade } = require('./Facade');
+const { AuthUser, Hasher, JwtDriver, AuthMiddleware, RoleMiddleware, AuthController, AuthServiceProvider } = require('../core');
+
+/**
+ * Auth facade.
+ *
+ * @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
+ *
+ * @see src/auth/Auth.js
+ */
+class Auth extends createFacade('auth') {}
+
+module.exports = { Auth, AuthUser, Hasher, JwtDriver, AuthMiddleware, RoleMiddleware, AuthController, AuthServiceProvider };

package/src/facades/Cache.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const {createFacade} = require('./Facade');
+
+/**
+ * Cache facade.
+ *
+ * @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
+ *
+ * @see src/cache/Cache.js
+ */
+class Cache extends createFacade('cache') {
+}
+
+module.exports = Cache;

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('../core');
+
+module.exports = {
+  Model,
+  fields,
+  QueryBuilder,
+  DatabaseManager,
+  SchemaBuilder,
+  MigrationRunner,
+  ModelInspector,
+  DatabaseServiceProvider,
+};

package/src/facades/Events.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const { createFacade } = require('./Facade');
+
+/**
+ * Events facade.
+ *
+ * @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
+ *
+ * @see src/events/EventEmitter.js
+ */
+class Events extends createFacade('events') {}
+
+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

@@ -0,0 +1,51 @@
+'use strict';
+
+const { createFacade } = require('./Facade');
+// const {PendingRequest,HttpResponse} = require('../http/HttpClient');
+
+/**
+ * Fluent outbound HTTP client facade.
+ * Resolved from the DI container — every method creates a fresh PendingRequest.
+ *
+ * @class
+ *
+ * — 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
+ *
+ * — 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
+ *
+ * — Concurrent
+ * @property {function(function): Promise<HttpResponse[]>}  pool
+ *
+ * — Testing
+ * @property {function(object): void} swap
+ * @property {function(): void}       restore
+ *
+ * @see src/http/HttpClient.js
+ */
+class Http extends createFacade('http') {}
+
+module.exports = Http;

package/src/facades/Log.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const {createFacade} = require('./Facade');
+
+
+/**
+ * Log facade.
+ *
+ * @class
+ * @property {function(TAG:string,message:string,...*): void}           v
+ * @property {function(TAG:string,message:string,...*): void}           d
+ * @property {function(TAG:string,message:string,...*): void}           i
+ * @property {function(TAG:string,message:string,...*): void}           w
+ * @property {function(TAG:string,message:string,...*): void}           e
+ * @property {function(TAG:string,message:string,...*): void}           wtf
+ * @property {function(TAG:string,message:string,...*): void}           verbose
+ * @property {function(TAG:string,message:string,...*): void}           debug
+ * @property {function(TAG:string,message:string,...*): void}           info
+ * @property {function(TAG:string,message:string,...*): void}           warn
+ * @property {function(TAG:string,message:string,...*): void}           error
+ * @property {function(string): TaggedLogger} tag
+ * @property {function(string): function}     time
+ * @property {function(string, function): Promise<*>} timed
+ * @property {function(object): void}         swap
+ * @property {function(): void}               restore
+ *
+ * @see src/logger/Logger.js
+ */
+class Log extends createFacade('log') {
+}
+
+module.exports = Log;

package/src/facades/Mail.js

@@ -0,0 +1,35 @@
+'use strict';
+
+const { createFacade } = require('./Facade');
+const { MailMessage, TemplateEngine, SmtpDriver, SendGridDriver, MailgunDriver, LogDriver, MailServiceProvider } = require('../core');
+
+/**
+ * Mail facade.
+ *
+ * @class
+ * @property {function(MailMessage|object): Promise<void>} send
+ * @property {function(MailMessage|object): Promise<void>} queue
+ * @property {function(string, string=): MailMessage}      to
+ * @property {function(object): void}                      swap
+ * @property {function(): void}                            restore
+ *
+ * — MailMessage builder (returned by Mail.to())
+ * @property {function(string, string=): MailMessage}           MailMessage.prototype.to
+ * @property {function(string, string=): MailMessage}           MailMessage.prototype.cc
+ * @property {function(string, string=): MailMessage}           MailMessage.prototype.bcc
+ * @property {function(string, string=): MailMessage}           MailMessage.prototype.from
+ * @property {function(string, string=): MailMessage}           MailMessage.prototype.replyTo
+ * @property {function(string): MailMessage}                    MailMessage.prototype.subject
+ * @property {function(string): MailMessage}                    MailMessage.prototype.html
+ * @property {function(string): MailMessage}                    MailMessage.prototype.text
+ * @property {function(string, object=): MailMessage}           MailMessage.prototype.view
+ * @property {function(string, string=, string=): MailMessage}  MailMessage.prototype.attach
+ * @property {function(number): MailMessage}                    MailMessage.prototype.priority
+ * @property {function(): Promise<void>}                        MailMessage.prototype.send
+ * @property {function(): Promise<void>}                        MailMessage.prototype.queue
+ *
+ * @see src/mail/Mail.js
+ */
+class Mail extends createFacade('mail') {}
+
+module.exports = Mail

package/src/facades/Queue.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const { createFacade } = require('./Facade');
+
+/**
+ * Queue facade.
+ *
+ * @class
+ * @property {function(Job): Promise<void>}          push
+ * @property {function(string=): Promise<number>}    size
+ * @property {function(string=): Promise<void>}      clear
+ * @property {function(function): void}              register
+ * @property {function(object): void}                swap
+ * @property {function(): void}                      restore
+ *
+ * @see src/queue/Queue.js
+ */
+class Queue extends createFacade('queue') {}
+
+/**
+ * Shorthand for Queue.push(job).
+ *
+ * @param {Job} job
+ * @returns {Promise<void>}
+ */
+async function dispatch(job) {
+  return Queue.push(job);
+}
+
+module.exports = Queue;

package/src/facades/Storage.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const { createFacade } = require('./Facade');
+
+/**
+ * Storage facade.
+ *
+ * @class
+ * @property {function(string, Buffer|string, object=): Promise<void>}    put
+ * @property {function(string): Promise<Buffer|string>}                   get
+ * @property {function(string): Promise<boolean>}                         exists
+ * @property {function(string): Promise<void>}                            delete
+ * @property {function(string): Promise<object>}                          metadata
+ * @property {function(string): string}                                   url
+ * @property {function(string): string}                                   path
+ * @property {function(string, object, object=): void}                    stream
+ * @property {function(string): Storage}                                  disk
+ * @property {function(object): void}                                     swap
+ * @property {function(): void}                                           restore
+ *
+ * @see src/storage/Storage.js
+ */
+class Storage extends createFacade('storage') {}
+
+module.exports = Storage;

package/src/facades/Url.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const {createFacade} = require('./Facade');
+
+/**
+ * URL facade — Laravel-like URL generation.
+ *
+ * @class
+ *
+ * — Base
+ * @property {function(): string}                                                  base
+ *
+ * — URL generation
+ * @property {function(string, object=): string}                                   to
+ * @property {function(string, object=): string}                                   secure
+ * @property {function(string, object=): string}                                   relative
+ *
+ * — Named routes
+ * @property {function(string, object=, object=): string}                          route
+ *
+ * — Assets
+ * @property {function(string): string}                                            asset
+ * @property {function(string): string}                                            secureAsset
+ *
+ * — Current / previous request
+ * @property {function(): string|null}                                             current
+ * @property {function(): string|null}                                             currentPath
+ * @property {function(string=): string}                                           previous
+ *
+ * — Signed URLs
+ * @property {function(string, object=, number=): string}                          signedRoute
+ * @property {function(string, number=): string}                                   signedUrl
+ * @property {function(object): boolean}                                           hasValidSignature
+ *
+ * — Scheme control
+ * @property {function(boolean=): UrlGenerator}                                    forceHttps
+ * @property {function(string): UrlGenerator}                                      forceScheme
+ * @property {function(string): UrlGenerator}                                      useAssetOrigin
+ *
+ * — Introspection
+ * @property {function(string): boolean}                                           isValid
+ * @property {function(...string): boolean}                                        is
+ *
+ * — Testing
+ * @property {function(object): void}                                              swap
+ * @property {function(): void}                                                    restore
+ *
+ * @see src/http/UrlGenerator.js
+ */
+class URL extends createFacade('url') {
+}
+
+module.exports = URL;