millas 0.2.12-beta → 0.2.12-beta-2

package/src/i18n/defaults.js

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * Millas framework default translatable strings.
+ *
+ * These are the strings used internally by Millas — validation messages,
+ * auth errors, admin panel labels, migration prompts, etc.
+ *
+ * When a developer runs `millas lang:publish sw --defaults`, these keys
+ * are merged into their locale file alongside their own app strings.
+ *
+ * Organised by module so translators know the context.
+ * All values are the English source text — same key = same value for 'en'.
+ *
+ * Format:
+ *   'key':              'English source text'   — simple string
+ *   'key':              ['singular', 'plural']  — plural form
+ *   'context|key':      'English source text'   — contextual
+ */
+module.exports = {
+
+  // ── Validation ─────────────────────────────────────────────────────────
+  'This field is required.':                        'This field is required.',
+  'Maximum {max} characters allowed.':              'Maximum {max} characters allowed.',
+  'Must be a whole number.':                        'Must be a whole number.',
+  'Must be a number.':                              'Must be a number.',
+  'Must be a valid email address.':                 'Must be a valid email address.',
+  'Must be a valid URL.':                           'Must be a valid URL.',
+  'Must be a valid date (YYYY-MM-DD).':             'Must be a valid date (YYYY-MM-DD).',
+  'Must be valid JSON.':                            'Must be valid JSON.',
+  'Must be a valid UUID.':                          'Must be a valid UUID.',
+  'Please select a value.':                         'Please select a value.',
+  'Please select a related record.':                'Please select a related record.',
+  'Invalid value. Must be one of: {values}':        'Invalid value. Must be one of: {values}',
+  'Password must be at least 8 characters.':        'Password must be at least 8 characters.',
+
+  // ── Auth ───────────────────────────────────────────────────────────────
+  'Email is required':                              'Email is required',
+  'Password is required':                           'Password is required',
+  'Invalid email or password':                      'Invalid email or password',
+  'Your account has been deactivated':              'Your account has been deactivated',
+  'Email already in use':                           'Email already in use',
+  'Passwords do not match':                         'Passwords do not match',
+  'Token has expired':                              'Token has expired',
+  'Invalid token':                                  'Invalid token',
+  'You are not authorized to perform this action':  'You are not authorized to perform this action',
+
+  // ── HTTP errors ────────────────────────────────────────────────────────
+  'Not Found':                                      'Not Found',
+  'Unauthorized':                                   'Unauthorized',
+  'Forbidden':                                      'Forbidden',
+  'Unprocessable Entity':                           'Unprocessable Entity',
+  'Internal Server Error':                          'Internal Server Error',
+  'Too Many Requests':                              'Too Many Requests',
+  '{model} #{id} not found':                        '{model} #{id} not found',
+
+  // ── Pagination ─────────────────────────────────────────────────────────
+  'Showing {from} to {to} of {total} results':      'Showing {from} to {to} of {total} results',
+  'Previous':                                       'Previous',
+  'Next':                                           'Next',
+  'Page {page} of {total}':                         'Page {page} of {total}',
+
+  // ── CRUD ───────────────────────────────────────────────────────────────
+  '{model} created successfully':                   '{model} created successfully',
+  '{model} updated successfully':                   '{model} updated successfully',
+  '{model} deleted':                                '{model} deleted',
+  'No records found':                               'No records found',
+  'Record not found':                               'Record not found',
+
+  // ── Plural CRUD ────────────────────────────────────────────────────────
+  '{count} record deleted':               ['{count} record deleted',    '{count} records deleted'],
+  '{count} record updated':               ['{count} record updated',    '{count} records updated'],
+
+  // ── Admin panel ────────────────────────────────────────────────────────
+  'Dashboard':                                      'Dashboard',
+  'Search':                                         'Search',
+  'Filters':                                        'Filters',
+  'Actions':                                        'Actions',
+  'Export CSV':                                     'Export CSV',
+  'Export JSON':                                    'Export JSON',
+  'Save':                                           'Save',
+  'Save and continue editing':                      'Save and continue editing',
+  'Save and add another':                           'Save and add another',
+  'Delete':                                         'Delete',
+  'Cancel':                                         'Cancel',
+  'Edit':                                           'Edit',
+  'Add {model}':                                    'Add {model}',
+  'Change {model}':                                 'Change {model}',
+  'Delete {model}':                                 'Delete {model}',
+  'Are you sure you want to delete {label}?':       'Are you sure you want to delete {label}?',
+  'This action cannot be undone.':                  'This action cannot be undone.',
+  'No {model} yet':                                 'No {model} yet',
+  'Select all':                                     'Select all',
+  'Deselect all':                                   'Deselect all',
+
+  // ── Admin status badges (contextual) ───────────────────────────────────
+  'status|active':                                  'Active',
+  'status|inactive':                                'Inactive',
+  'status|pending':                                 'Pending',
+  'status|approved':                                'Approved',
+  'status|rejected':                                'Rejected',
+  'status|draft':                                   'Draft',
+  'status|published':                               'Published',
+
+  // ── Admin login ────────────────────────────────────────────────────────
+  'Sign in to your account':                        'Sign in to your account',
+  'Email address':                                  'Email address',
+  'Password':                                       'Password',
+  'Remember me':                                    'Remember me',
+  'Sign in':                                        'Sign in',
+  'Sign out':                                       'Sign out',
+  'You have been logged out.':                      'You have been logged out.',
+
+  // ── Migration prompts ──────────────────────────────────────────────────
+  'No changes detected.':                           'No changes detected.',
+  'Migrations generated:':                          'Migrations generated:',
+  'Run: millas migrate   to apply.':                'Run: millas migrate   to apply.',
+
+  // ── Queue ──────────────────────────────────────────────────────────────
+  'Job failed: {message}':                          'Job failed: {message}',
+  'Job completed: {job}':                           'Job completed: {job}',
+};

package/src/i18n/index.js

@@ -0,0 +1,164 @@
+'use strict';
+
+const Translator = require('./Translator');
+
+/**
+ * Trans — global translation singleton + shorthand helpers.
+ *
+ * This is the object you import in controllers, models, views, and commands.
+ * It wraps the Translator instance with the Django-style shorthand functions.
+ *
+ * ── Import styles ──────────────────────────────────────────────────────────
+ *
+ *   // Named destructuring (recommended)
+ *   const { __, _n, _p, _f } = require('millas/src/i18n');
+ *
+ *   // Full facade for locale control
+ *   const { Trans } = require('millas/src/i18n');
+ *   Trans.setLocale('sw');
+ *
+ * ── API ────────────────────────────────────────────────────────────────────
+ *
+ *   __('Hello')
+ *   → 'Habari'   (when locale=sw)
+ *   → 'Hello'    (when locale=en or no translation found)
+ *
+ *   _n('You have %d message', 'You have %d messages', 3)
+ *   → 'Una ujumbe 3'
+ *
+ *   _p('menu', 'File')
+ *   → 'Faili'   (contextual — same word, different contexts)
+ *
+ *   _f('Welcome, {name}!', { name: 'Alice' })
+ *   → 'Karibu, Alice!'
+ *
+ *   _f('Hello %s, you have %d items', 'Alice', 5)
+ *   → 'Habari Alice, una vitu 5'
+ *
+ *   _fn('You have %d item', 'You have %d items', 3)
+ *   → 'Una vitu 3'
+ *
+ * ── In templates (Nunjucks) ────────────────────────────────────────────────
+ *
+ *   Add the filters via I18nServiceProvider (done automatically):
+ *
+ *   {{ 'Hello' | __ }}
+ *   {{ 'You have %d messages' | _n(count) }}
+ *   {{ 'Welcome, {name}!' | _f({ name: user.name }) }}
+ *
+ * ── In CLI commands ────────────────────────────────────────────────────────
+ *
+ *   const { __ } = require('millas/src/i18n');
+ *   console.log(__('Migrations applied successfully.'));
+ */
+
+// ── Singleton Translator instance ────────────────────────────────────────────
+const Trans = new Translator();
+
+// ── Shorthand functions ───────────────────────────────────────────────────────
+
+/**
+ * gettext — translate a string.
+ *
+ *   __('Hello')
+ *   __('Hello', 'sw')    // explicit locale override
+ *
+ * @param {string} key
+ * @param {string} [locale]
+ * @returns {string}
+ */
+function __(key, locale) {
+  return Trans.translate(key, locale);
+}
+
+/**
+ * ngettext — singular/plural translation.
+ *
+ *   _n('You have %d message', 'You have %d messages', count)
+ *
+ * Note: this does NOT interpolate %d — call _fn() if you also need
+ * the count substituted into the string.
+ *
+ * @param {string} singular
+ * @param {string} plural
+ * @param {number} count
+ * @param {string} [locale]
+ * @returns {string}
+ */
+function _n(singular, plural, count, locale) {
+  return Trans.ngettext(singular, plural, count, locale);
+}
+
+/**
+ * pgettext — contextual translation.
+ *
+ *   _p('menu', 'File')     // the menu item "File"
+ *   _p('action', 'File')   // the action "to file something"
+ *
+ * @param {string} context
+ * @param {string} key
+ * @param {string} [locale]
+ * @returns {string}
+ */
+function _p(context, key, locale) {
+  return Trans.pgettext(context, key, locale);
+}
+
+/**
+ * format — translate + interpolate named or positional variables.
+ *
+ *   _f('Welcome, {name}!', { name: 'Alice' })
+ *   _f('Hello %s, you have %d items', 'Alice', 5)
+ *
+ * @param {string} key
+ * @param {...*}   args
+ * @returns {string}
+ */
+function _f(key, ...args) {
+  return Trans.format(key, ...args);
+}
+
+/**
+ * nformat — plural translation + interpolation.
+ *
+ *   _fn('You have %d item', 'You have %d items', count)
+ *   // → 'You have 3 items'  (count is auto-interpolated as first %d)
+ *
+ * @param {string} singular
+ * @param {string} plural
+ * @param {number} count
+ * @param {...*}   args  — additional interpolation values after count
+ * @returns {string}
+ */
+function _fn(singular, plural, count, ...args) {
+  return Trans.nformat(singular, plural, count, ...args);
+}
+
+/**
+ * lazy — returns a lazy-evaluated translation proxy.
+ *
+ * Useful when the translation needs to be stored before the locale is set
+ * (e.g. in class-level constants, model field labels).
+ *
+ *   const label = lazy__('Email address');
+ *   // label() → 'Anwani ya barua pepe'   (evaluated at call time)
+ *
+ * @param {string} key
+ * @returns {Function}
+ */
+function lazy__(key) {
+  return () => Trans.translate(key);
+}
+
+module.exports = {
+  // Singleton for locale control + advanced usage
+  Trans,
+
+  // Shorthand functions
+  __,
+  _n,
+  _p,
+  _f,
+  _fn,
+  lazy__,
+};

package/src/i18n/locales/en.js

@@ -0,0 +1,55 @@
+'use strict';
+
+/**
+ * English (en) — source language catalogue.
+ *
+ * For the source language this file acts as documentation:
+ * it lists every translatable string in the application.
+ * Values are the same as keys — no actual translation needed.
+ *
+ * Other locale files only need to include keys where the translation
+ * differs. Missing keys fall back to this file, then to the raw key.
+ *
+ * ── Auth ──────────────────────────────────────────────────────────────────
+ */
+module.exports = {
+
+  // ── Auth / validation ────────────────────────────────────────────────────
+  'Email is required':                      'Email is required',
+  'Password is required':                   'Password is required',
+  'Invalid email or password':              'Invalid email or password',
+  'Your account has been deactivated':      'Your account has been deactivated',
+  'Email already in use':                   'Email already in use',
+  'Password must be at least 8 characters': 'Password must be at least 8 characters',
+  'Passwords do not match':                 'Passwords do not match',
+
+  // ── CRUD messages ────────────────────────────────────────────────────────
+  '%s created successfully':                '%s created successfully',
+  '%s updated successfully':                '%s updated successfully',
+  '%s deleted':                             '%s deleted',
+  'No records found':                       'No records found',
+  'Record not found':                       'Record not found',
+
+  // ── Pagination ───────────────────────────────────────────────────────────
+  'Showing %d to %d of %d results':         'Showing %d to %d of %d results',
+  'Previous':                               'Previous',
+  'Next':                                   'Next',
+
+  // ── Plural examples ──────────────────────────────────────────────────────
+  // Array format: [singular_form, plural_form, ...]
+  'You have %d message':                    ['You have %d message',  'You have %d messages'],
+  '%d item selected':                       ['%d item selected',     '%d items selected'],
+  '%d record deleted':                      ['%d record deleted',    '%d records deleted'],
+
+  // ── Contextual examples (context|key) ────────────────────────────────────
+  'menu|File':                              'File',
+  'menu|Edit':                              'Edit',
+  'status|active':                          'Active',
+  'status|inactive':                        'Inactive',
+  'status|pending':                         'Pending',
+
+  // ── Named interpolation examples ─────────────────────────────────────────
+  'Welcome, {name}!':                       'Welcome, {name}!',
+  'Hello, {name}. You have {count} notifications.':
+    'Hello, {name}. You have {count} notifications.',
+};

package/src/i18n/locales/sw.js

@@ -0,0 +1,48 @@
+'use strict';
+
+/**
+ * Swahili (sw) translation catalogue.
+ *
+ * Only include keys where the translation differs from the source.
+ * Missing keys automatically fall back to the fallback locale (en).
+ */
+module.exports = {
+
+  // ── Auth / validation ────────────────────────────────────────────────────
+  'Email is required':                      'Barua pepe inahitajika',
+  'Password is required':                   'Nywila inahitajika',
+  'Invalid email or password':              'Barua pepe au nywila si sahihi',
+  'Your account has been deactivated':      'Akaunti yako imezimwa',
+  'Email already in use':                   'Barua pepe hiyo tayari inatumika',
+  'Password must be at least 8 characters': 'Nywila lazima iwe na herufi angalau 8',
+  'Passwords do not match':                 'Nywila hazifanani',
+
+  // ── CRUD messages ────────────────────────────────────────────────────────
+  '%s created successfully':                '%s imeundwa kikamilifu',
+  '%s updated successfully':                '%s imesasishwa kikamilifu',
+  '%s deleted':                             '%s imefutwa',
+  'No records found':                       'Hakuna rekodi zilizopatikana',
+  'Record not found':                       'Rekodi haijapatikana',
+
+  // ── Pagination ───────────────────────────────────────────────────────────
+  'Showing %d to %d of %d results':         'Inaonyesha %d hadi %d kati ya %d matokeo',
+  'Previous':                               'Iliyotangulia',
+  'Next':                                   'Inayofuata',
+
+  // ── Plural forms (Swahili uses same form for all counts) ─────────────────
+  'You have %d message':                    ['Una ujumbe %d', 'Una ujumbe %d'],
+  '%d item selected':                       ['%d kipengele kimechaguliwa', '%d vipengele vimechaguliwa'],
+  '%d record deleted':                      ['Rekodi %d imefutwa', 'Rekodi %d zimefutwa'],
+
+  // ── Contextual ───────────────────────────────────────────────────────────
+  'menu|File':      'Faili',
+  'menu|Edit':      'Hariri',
+  'status|active':  'Amilifu',
+  'status|inactive':'Haifanyi kazi',
+  'status|pending': 'Inasubiri',
+
+  // ── Named interpolation ──────────────────────────────────────────────────
+  'Welcome, {name}!':  'Karibu, {name}!',
+  'Hello, {name}. You have {count} notifications.':
+    'Habari {name}. Una arifa {count}.',
+};

package/src/index.js

@@ -1,147 +1,8 @@
 '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');
+const Millas = require('./container/MillasApp');
 
-// ── Validation ────────────────────────────────────────────────────
-const {
-  Validator,
-  BaseValidator,
-  StringValidator,
-  EmailValidator,
-  NumberValidator,
-  BooleanValidator,
-  DateValidator,
-  ArrayValidator,
-  ObjectValidator,
-  FileValidator,
-  string,
-  email,
-  number,
-  boolean,
-  date,
-  array,
-  object: objectField,
-  file:   fileField,
-} = require('./validation/Validator');
-const MillasApp = require('./container/MillasApp');
-// ── HTTP Layer (old) ──────────────────────────────────────────────
-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');
-
-// ── DI Container ─────────────────────────────────────────────────
-const Container          = require('./container/Container');
-const Application        = require('./container/Application');
-const ServiceProvider    = require('./providers/ServiceProvider');
-const ProviderRegistry   = require('./providers/ProviderRegistry');
-
-// ── ORM ───────────────────────────────────────────────────────────
-const { Model, fields, QueryBuilder, DatabaseManager,
-        SchemaBuilder, MigrationRunner, ModelInspector } = require('./orm');
-const DatabaseServiceProvider = require('./providers/DatabaseServiceProvider');
-
-// ── Auth ──────────────────────────────────────────────────────────
-const Auth                = require('./auth/Auth');
-const Hasher              = require('./auth/Hasher');
-const JwtDriver           = require('./auth/JwtDriver');
-const AuthMiddleware      = require('./auth/AuthMiddleware');
-const RoleMiddleware      = require('./auth/RoleMiddleware');
-const AuthController      = require('./auth/AuthController');
-const AuthServiceProvider = require('./providers/AuthServiceProvider');
-
-// ── Mail ──────────────────────────────────────────────────────────
-const { Mail, MailMessage, TemplateEngine,
-        SmtpDriver, SendGridDriver, MailgunDriver, LogDriver } = require('./mail');
-const MailServiceProvider = require('./providers/MailServiceProvider');
-
-// ── Queue ─────────────────────────────────────────────────────────
-const Queue              = require('./queue/Queue');
-const Job                = require('./queue/Job');
-const QueueWorker        = require('./queue/workers/QueueWorker');
-const { dispatch }       = require('./queue/Queue');
-const QueueServiceProvider = require('./providers/QueueServiceProvider');
-
-// ── 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 App
-  MillasApp,
-  // ── Millas HTTP layer ──────────────────────────────────────────
-  MillasRequest, MillasResponse, ResponseDispatcher, RequestContext,
-  jsonify, view, redirect, text, send_file:file, empty,
-  abort, notFound, unauthorized, forbidden,
-  // ── Validation ────────────────────────────────────────────────
-  Validator,
-  BaseValidator,
-  StringValidator, EmailValidator, NumberValidator, BooleanValidator,
-  DateValidator, ArrayValidator, ObjectValidator, FileValidator,
-  string, email, number, boolean, date, array,
-  object: objectField,
-  file:   fileField,
-  // HTTP
-  Controller, Middleware, MiddlewarePipeline,
-  CorsMiddleware, ThrottleMiddleware, LogMiddleware, HttpError,
-  // DI
-  Container, Application, ServiceProvider, ProviderRegistry,
-  // ORM
-  Model, fields, QueryBuilder, DatabaseManager, SchemaBuilder,
-  MigrationRunner, ModelInspector, DatabaseServiceProvider,
-  // Auth
-  Auth, Hasher, JwtDriver, AuthMiddleware, RoleMiddleware,
-  AuthController, AuthServiceProvider,
-  // Mail
-  Mail, MailMessage, TemplateEngine,
-  SmtpDriver, SendGridDriver, MailgunDriver, LogDriver, MailServiceProvider,
-  // Queue
-  Queue, Job, QueueWorker, dispatch, QueueServiceProvider,
-  // Events
-  EventEmitter, Event, Listener, emit, EventServiceProvider,
-  // Cache
-  Cache, MemoryDriver, FileDriver, NullDriver, CacheServiceProvider,
-  // Storage
-  Storage, LocalDriver, StorageServiceProvider,
-};
-
-// ── Admin ─────────────────────────────────────────────────────────
-const { Admin, AdminResource, AdminField, AdminFilter } = require('./admin');
-const AdminServiceProvider = require('./providers/AdminServiceProvider');
-
-Object.assign(module.exports, {
-  Admin, AdminResource, AdminField, AdminFilter, AdminServiceProvider,
-});
+/**
+ * @module millas
+ */
+module.exports = { Millas };