@nutin/cli 1.3.1 → 2.1.0

package/templates/base/src/core/base-classes/service/service.test.js.hbs

@@ -0,0 +1,150 @@
+import { Service } from '#root/dist/src/core/base-classes/service/service.js';
+
+class TestService extends Service {
+  constructor() {
+    super();
+    this.destroyCalls = 0;
+    this.cleanupCalls = [];
+  }
+
+  addCleanup(fn) {
+    this.registerCleanup(fn);
+  }
+
+  onDestroy() {
+    this.destroyCalls++;
+  }
+
+  ping() {
+    return this;
+  }
+}
+
+class OtherTestService extends Service {
+  constructor() {
+    super();
+    this.destroyCalls = 0;
+  }
+
+  onDestroy() {
+    this.destroyCalls++;
+  }
+}
+
+describe('Service', () => {
+  afterEach(() => {
+    TestService.testingResetAll();
+    OtherTestService.testingResetAll();
+  });
+
+  it('throws when instantiated directly instead of via getInstance', () => {
+    expect(() => new TestService()).toThrow('TestService is a Service. Use TestService.getInstance() instead.');
+  });
+
+  it('creates the instance lazily on first getInstance call', () => {
+    expect(Service.hasInstance(TestService)).toBe(false);
+    const instance = TestService.getInstance();
+    expect(instance).toBeInstanceOf(TestService);
+    expect(Service.hasInstance(TestService)).toBe(true);
+  });
+
+  it('returns the same instance on repeated getInstance calls without args', () => {
+    const instance1 = TestService.getInstance();
+    const instance2 = TestService.getInstance();
+    expect(instance1).toBe(instance2);
+  });
+
+  it('throws if getInstance is called with args on an already-initialized instance', () => {
+    TestService.getInstance();
+    expect(() => TestService.getInstance('arg')).toThrow('already initialized');
+  });
+
+  it('does not throw when getInstance is called with args for a fresh instance', () => {
+    expect(() => TestService.getInstance()).not.toThrow();
+  });
+
+  it('hasInstance reflects whether an instance has been created', () => {
+    expect(Service.hasInstance(TestService)).toBe(false);
+    TestService.getInstance();
+    expect(Service.hasInstance(TestService)).toBe(true);
+  });
+
+  it('registerCleanup callbacks run on dispose and are cleared afterward', () => {
+    const instance = TestService.getInstance();
+    let cleaned = false;
+    instance.addCleanup(() => { cleaned = true; });
+
+    instance.dispose();
+
+    expect(cleaned).toBe(true);
+    expect(Service.hasInstance(TestService)).toBe(false);
+  });
+
+  it('dispose clears cleanup callbacks so they only run once', () => {
+    const instance = TestService.getInstance();
+    let calls = 0;
+    instance.addCleanup(() => { calls++; });
+
+    instance.dispose();
+    instance.dispose();
+
+    expect(calls).toBe(1);
+  });
+
+  it('destroy calls onDestroy and removes the instance from the registry', async () => {
+    const instance = TestService.getInstance();
+    await TestService.destroy();
+
+    expect(instance.destroyCalls).toBe(1);
+    expect(Service.hasInstance(TestService)).toBe(false);
+  });
+
+  it('destroy is a no-op when no instance exists', async () => {
+    expect(Service.hasInstance(TestService)).toBe(false);
+    await TestService.destroy();
+    expect(Service.hasInstance(TestService)).toBe(false);
+  });
+
+  it('destroyAll calls onDestroy on every instance and clears the registry', async () => {
+    const a = TestService.getInstance();
+    const b = OtherTestService.getInstance();
+
+    await Service.destroyAll();
+
+    expect(a.destroyCalls).toBe(1);
+    expect(b.destroyCalls).toBe(1);
+    expect(Service.hasInstance(TestService)).toBe(false);
+    expect(Service.hasInstance(OtherTestService)).toBe(false);
+  });
+
+  it('autoBindMethods binds subclass methods so they work detached from the instance', () => {
+    const instance = TestService.getInstance();
+    const { ping } = instance;
+    expect(ping()).toBe(instance);
+  });
+
+  it('testingReset removes only the targeted instance without running cleanup', () => {
+    const instance1 = TestService.getInstance();
+    let cleaned = false;
+    instance1.addCleanup(() => { cleaned = true; });
+
+    TestService.testingReset();
+
+    expect(cleaned).toBe(false);
+    const instance2 = TestService.getInstance();
+    expect(instance1).not.toBe(instance2);
+  });
+
+  it('testingResetAll clears every instance without running cleanup', () => {
+    const a = TestService.getInstance();
+    OtherTestService.getInstance();
+    let cleaned = false;
+    a.addCleanup(() => { cleaned = true; });
+
+    Service.testingResetAll();
+
+    expect(cleaned).toBe(false);
+    expect(Service.hasInstance(TestService)).toBe(false);
+    expect(Service.hasInstance(OtherTestService)).toBe(false);
+  });
+});

package/templates/base/src/core/base-classes/service/service.ts.hbs

@@ -1,15 +1,15 @@
 /**
- * Abstract  class for implementing the Singleton pattern.
+ * Abstract class for implementing the Singleton pattern.
  * Supports constructor parameters for initialization.
  */
 export abstract class Service<T extends Service<T>> {
   private static _instances = new Map<Function, any>();
   private static _instantiating = new Set<Function>();
   private _cleanupCallbacks: (() => void)[] = [];
-  
+
   constructor(...args: any[]) {
     const constructor = this.constructor as new (...args: any[]) => T;
-    
+
     if (!Service._instantiating.has(constructor)) {
       throw new Error(
         `${constructor.name} is a Service. Use ${constructor.name}.getInstance() instead.`
@@ -19,31 +19,39 @@ export abstract class Service<T extends Service<T>> {
     window.addEventListener('beforeunload', this.dispose);
   }
 
-  public static createInstance<T extends Service<T>>(
-    constructor: new (...args: any[]) => T,
+  /**
+   * Returns the singleton instance, creating it with the provided args if it
+   * doesn't exist yet. Throws if args are passed to an already-initialized instance,
+   * preventing silent re-initialization mismatches.
+   */
+  public static getInstance<T extends Service<T>>(
+    this: new (...args: any[]) => T,
     ...args: any[]
   ): T {
-    if (!Service._instances.has(constructor)) {
-      Service._instantiating.add(constructor);
-      Service._instances.set(constructor, new constructor(...args));
-      Service._instantiating.delete(constructor);
+    const alreadyExists = Service._instances.has(this);
+
+    if (alreadyExists && args.length > 0) {
+      throw new Error(
+        `${this.name} is already initialized. ` +
+        `getInstance() was called with arguments on an existing instance, ` +
+        `which would silently ignore them. ` +
+        `Call getInstance() without arguments to retrieve the existing instance.`
+      );
     }
-    return Service._instances.get(constructor);
-  }
 
-  public static getInstance<T extends Service<T>>(this: new () => T): T {
-    if (!Service._instances.has(this)) {
+    if (!alreadyExists) {
       Service._instantiating.add(this);
-      Service._instances.set(this, new this());
+      Service._instances.set(this, new this(...args));
       Service._instantiating.delete(this);
     }
+
     return Service._instances.get(this);
   }
 
   public static hasInstance<T extends Service<T>>(
     constructor: new (...args: any[]) => T
   ): boolean {
-    return Service._instances.has(constructor);  
+    return Service._instances.has(constructor);
   }
 
   public static async destroy<T extends Service<T>>(
@@ -65,7 +73,7 @@ export abstract class Service<T extends Service<T>> {
   public static async destroyAll(): Promise<void> {
     const destroyPromises = Array.from(Service._instances.values())
       .map(instance => instance.onDestroy());
-    
+
     await Promise.all(destroyPromises);
     Service._instances.clear();
     Service._instantiating.clear();
@@ -76,11 +84,9 @@ export abstract class Service<T extends Service<T>> {
   }
 
   /**
-   * For async and custom cleanup operations
+   * For async and custom cleanup operations.
    */
-  protected onDestroy<T extends Service<T>>(this: () => T): void {
-    console.log(`No onDestroy operations.`)
-  }
+  protected onDestroy(): void {}
 
   private autoBindMethods(): void {
     let proto = Object.getPrototypeOf(this);

package/templates/base/src/core/base-classes/view/view.test.js.hbs

@@ -0,0 +1,71 @@
+import { View } from '#root/dist/src/core/index.js';
+
+class HomeView extends View {}
+class NamedView extends View {}
+
+describe('View', () => {
+  let app;
+
+  beforeEach(() => {
+    app = document.getElementById('app');
+  });
+
+  afterEach(() => {
+    app.innerHTML = '';
+    app = null;
+  });
+
+  it('throws when viewName is omitted', () => {
+    expect(() => new HomeView({})).toThrow();
+  });
+
+  it('throws when viewName is an empty string', () => {
+    expect(() => new HomeView({ viewName: '' })).toThrow();
+  });
+
+  it('uses the explicit viewName option', () => {
+    const view = new NamedView({ viewName: 'custom-name' });
+    expect(view.viewName).toBe('custom-name');
+  });
+
+  it('generateTemplate() returns the constructor template', () => {
+    const view = new HomeView({ viewName: 'home', template: '<p>hi</p>' });
+    expect(view.render().innerHTML).toBe('<p>hi</p>');
+  });
+
+  it('defaults the template to an empty string', () => {
+    const view = new HomeView({ viewName: 'home' });
+    expect(view.render().innerHTML).toBe('');
+  });
+
+  it('defaults the tagName to "section"', () => {
+    const view = new HomeView({ viewName: 'home' });
+    expect(view.getElement().tagName).toBe('SECTION');
+  });
+
+  it('setRouteParams/getRouteParams/getRouteParam/hasRouteParam manage route params', () => {
+    const view = new HomeView({ viewName: 'home' });
+    expect(view.hasRouteParam('id')).toBe(false);
+    expect(view.getRouteParam('id')).toBeUndefined();
+
+    view.setRouteParams({ id: '42' });
+
+    expect(view.hasRouteParam('id')).toBe(true);
+    expect(view.getRouteParam('id')).toBe('42');
+    expect(view.getRouteParams()).toEqual({ id: '42' });
+  });
+
+  it('getRouteParams() returns a copy, not a live reference', () => {
+    const view = new HomeView({ viewName: 'home' });
+    view.setRouteParams({ id: '1' });
+    const params = view.getRouteParams();
+    params.id = 'mutated';
+    expect(view.getRouteParam('id')).toBe('1');
+  });
+
+  it('onEnter and onExit are present as no-op hooks', () => {
+    const view = new HomeView({ viewName: 'home' });
+    expect(() => view.onEnter()).not.toThrow();
+    expect(() => view.onExit()).not.toThrow();
+  });
+});

package/templates/base/src/core/base-classes/view/view.ts.hbs

@@ -1,77 +1,52 @@
 import { BaseComponent, BaseComponentOptions } from '../../index.js';
 
 export interface ViewOptions extends BaseComponentOptions {
-  viewName?: string;
+  viewName: string;
 }
 
 export abstract class View<T extends HTMLElement = HTMLElement> extends BaseComponent<T> {
-  public viewName: string;
+  private _viewName: string;
   protected routeParams: Record<string, string> = {};
+  private _template: string;
 
   constructor({
-      template,
-      tagName = 'section',
-      mountTarget = '#app',
-      viewName
-    }: ViewOptions) {
-    super({template, mountTarget, tagName});
-    this.viewName = viewName || this.getKebabCaseViewName();
+    template,
+    tagName = 'section',
+    mountTarget = '#app',
+    viewName,
+    trustLevel,
+  }: ViewOptions) {
+    super({ mountTarget, tagName, trustLevel });
+    if (!viewName) throw new Error('View requires a viewName.');
+    this._template = template ?? '';
+    this._viewName = viewName;
+  }
+
+  public get viewName(): string {
+    return this._viewName;
+  }
+
+  protected override generateTemplate(): string {
+    return this._template;
   }
 
-   /**
-   * Set route parameters for this view instance
-   * Called by the router when the view is instantiated
-   */
   public setRouteParams(params: Record<string, string>): void {
     this.routeParams = { ...params };
   }
 
-  /**
-   * Get all route parameters
-   */
   public getRouteParams(): Record<string, string> {
     return { ...this.routeParams };
   }
 
-  /**
-   * Get a specific route parameter
-   */
   public getRouteParam(key: string): string | undefined {
     return this.routeParams[key];
   }
 
-  /**
-   * Check if a route parameter exists and has a value
-   */
   public hasRouteParam(key: string): boolean {
     return key in this.routeParams && this.routeParams[key] !== undefined;
   }
 
-  public shouldUpdateMetaContent(): boolean {
-    return true;
-  }
-  
-  public onEnter(): void {
-    console.log(`${this.viewName} mounted with params:`, this.routeParams);
-  }
-
-  public onExit(): void {
-    console.log(`${this.viewName} unmounted`);
-  }
-
-  public override render(): HTMLElement {
-    this.onEnter();
-    return super.render();
-  }
-
-  public override destroy(): void {
-    super.destroy();
-    this.onExit();
-  }
-
-  private getKebabCaseViewName(): string {
-    const className = this.constructor.name;
-    const baseName = className.replace(/View$/, '');
-    return baseName.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
-  }
+  // Navigation hooks — called by router only, never by render lifecycle
+  public onEnter(): void {}
+  public onExit(): void {}
 }

package/templates/base/src/core/config.ts.hbs

@@ -0,0 +1,10 @@
+import langs from '../../config/languages.json' with { type: 'json' };
+import seo from '../../config/seo.json' with { type: 'json' };
+import nutinConfig from '../../nutin.config.js';
+
+export const CONFIG = {
+  langs,
+  seo,
+  i18n: nutinConfig.i18n,
+  generateSEOFiles: nutinConfig.generateSEOFiles,
+} as const;

package/templates/base/src/core/index.ts.hbs

@@ -3,6 +3,3 @@ export * from './base-classes/index.js';
 
 // Core functionalities
 export * from './services/index.js';
-
-// Helper functions
-export * from './utils/index.js';

package/templates/base/src/core/internals.d.ts.hbs

@@ -0,0 +1,27 @@
+declare interface NavigationEventMap {
+  'navigate': { path: string };
+  'reload': {};
+}
+
+declare interface LifecycleEventMap {
+  'before-render': {};
+  'after-render': {};
+  'before-destroy': {};
+  'after-destroy': {};
+  'view-mount': { viewName: string };
+  'view-unmount': { viewName: string };
+}
+
+declare interface I18nEventMap {
+  'language-changed': {
+    lang: string;
+  };
+}
+
+declare interface FrameworkEventMap extends NavigationEventMap, LifecycleEventMap, I18nEventMap {}
+
+declare interface AppEventMap {}
+
+declare interface EventMap extends FrameworkEventMap, AppEventMap {}
+
+declare type EventKey = keyof EventMap;

package/templates/base/src/core/nutin-config.d.ts.hbs

@@ -0,0 +1,4 @@
+declare module '*/nutin.config.js' {
+  const nutinConfig: { i18n: boolean; [key: string]: unknown };
+  export default nutinConfig;
+}

package/templates/base/src/core/services/event-bus/event-bus.test.js.hbs

@@ -127,11 +127,75 @@ describe('EventBus', () => {
   });
   it('should reset all service instances', () => {
     const eventBus1 = EventBus.getInstance();
-      
+
     EventBus.testingResetAll();
-      
+
     const eventBus2 = EventBus.getInstance();
-      
+
     expect(eventBus1).not.toBe(eventBus2);
   });
+
+  it('should only invoke a once() handler on the first emit', () => {
+    let callCount = 0;
+    eventBus.once('user-login', () => { callCount++; });
+
+    eventBus.emit('user-login', { userId: '1' });
+    expect(callCount).toBe(1);
+
+    eventBus.emit('user-login', { userId: '2' });
+    expect(callCount).toBe(1);
+  });
+
+  it('should auto-unsubscribe a once() handler from _subscriptions after it fires', () => {
+    eventBus.once('user-login', () => {});
+    expect(eventBus._subscriptions.length).toBe(1);
+
+    eventBus.emit('user-login', {});
+    expect(eventBus._subscriptions.length).toBe(0);
+  });
+
+  it('should not remove a once() subscription before it has fired', () => {
+    eventBus.once('user-login', () => {});
+    eventBus.emit('notification', {});
+    expect(eventBus._subscriptions.length).toBe(1);
+  });
+
+  it('should let a once() handler and a regular subscriber on the same event coexist', () => {
+    let onceCalls = 0;
+    let regularCalls = 0;
+    eventBus.once('notification', () => { onceCalls++; });
+    eventBus.subscribe('notification', () => { regularCalls++; });
+
+    eventBus.emit('notification', {});
+    expect(onceCalls).toBe(1);
+    expect(regularCalls).toBe(1);
+
+    eventBus.emit('notification', {});
+    expect(onceCalls).toBe(1);
+    expect(regularCalls).toBe(2);
+  });
+
+  it('off(event) with no callback removes every handler for that event', () => {
+    let callsA = 0;
+    let callsB = 0;
+    eventBus.subscribe('notification', () => { callsA++; });
+    eventBus.subscribe('notification', () => { callsB++; });
+
+    eventBus.off('notification');
+    eventBus.emit('notification', {});
+
+    expect(callsA).toBe(0);
+    expect(callsB).toBe(0);
+    expect(eventBus.handlers['notification']).toBeUndefined();
+  });
+
+  it('off(event) with no callback does not affect other events', () => {
+    let called = false;
+    eventBus.subscribe('user-login', () => { called = true; });
+
+    eventBus.off('notification');
+    eventBus.emit('user-login', {});
+
+    expect(called).toBe(true);
+  });
 });

package/templates/base/src/core/services/event-bus/event-bus.ts.hbs

@@ -2,7 +2,7 @@ import { Service } from "../../index.js";
 
 export type IEventBus = InstanceType<typeof EventBus>;
 
-type Subscription<K extends EventKey = EventKey> = {
+export type Subscription<K extends EventKey = EventKey> = {
   event: K;
   callback: (data: EventMap[K]) => void;
   once?: boolean;
@@ -58,7 +58,10 @@ export class EventBus extends Service<EventBus> {
     if (!handlers) return;
 
     if (callback) {
-      this.handlers[event] = handlers.filter(h => h !== callback);
+      (this.handlers as Record<
+        EventKey,
+        Array<(data: EventMap[K]) => void>
+      >)[event] = handlers.filter(h => h !== callback);
     } else {
       delete this.handlers[event];
     }
@@ -76,8 +79,10 @@ export class EventBus extends Service<EventBus> {
     if (!this.handlers[event]) {
       this.handlers[event] = [];
     }
-    this.handlers[event]!.push(callback);
-    this._subscriptions.push({ event, callback, once });
+    (
+      this.handlers as Record<EventKey, Array<(data: EventMap[K]) => void>>
+    )[event].push(callback);
+    this._subscriptions.push({ event, callback, once } as Subscription);
   }
 
   private cleanupEventListeners = (): void => {

package/templates/base/src/core/services/event-bus/index.ts.hbs

@@ -0,0 +1,3 @@
+export * from './event-bus.js';
+export * from './lifecycle.facade.js';
+export * from './navigation.facade.js';