Extending Tempo with Plugins

Tempo is designed with a "lean core" philosophy. While it provides robust date-time manipulation and parsing out of the box, advanced functionality (like reactive Tickers or domain-specific business logic) is added through a flexible Plugin System.

To manually register a plugin, use the static extend method. This is typically used for "opt-in" features or when you need to provide specific configuration to a plugin factory.

import { Tempo } from '@magmacomputing/tempo/core';
import { MyPlugin } from './my-plugin.js';
import { HolidayModule } from './my-holiday-plugin.js';

// Manual registration
Tempo.extend(MyPlugin);

// Registration with a Factory (providing options)
Tempo.extend(HolidayModule({ region: 'US-NY' }));

---

The most efficient way to author a plugin is using the defineExtension factory. This helper automatically handles the internal registration logic, making your plugin available as soon as it is imported (via side effect).

Example Plugin

import { defineExtension } from '@magmacomputing/tempo/plugin-api';

export const MyPlugin = defineExtension({
  name: 'MyPlugin',
  install(TempoClass: any) {
    // 1. Add a static method
  TempoClass.myStaticMethod = () => { /* ... */ };

  // 2. Add an instance method (on the prototype)
  TempoClass.prototype.toHoliday = function() {
    return factory(this.add({ days: 1 }));
  }
});

Manual Registration Pattern

If you prefer not to use the factory (e.g. for plugins that should not self-register), you can export a plain function with the Tempo.Plugin signature:

import type { Tempo } from '@magmacomputing/tempo/core';

export const ManualPlugin: Tempo.Plugin = (TempoClass, options, factory) => {
  // ... implementation ...
}

Type Safety (TypeScript)

To ensure your plugin is discoverable by the IDE, use Module Augmentation to extend the Tempo namespace and the Tempo class interface.

declare module '@magmacomputing/tempo/core' {
  namespace Tempo {
    // 1. Define new types/interfaces here
    interface HolidayOptions { ... }

    // 2. Add static methods to the Tempo namespace
    function myStaticMethod(): void;
  }

  interface Tempo {
    // 3. Add instance methods to the Tempo class
    toHoliday(): Tempo;
  }
}

Understanding Tempo Versions:

• @magmacomputing/tempo/core (Lite): A bare-bones engine with zero side-effects. This is the recommended choice for production builds and plugin authoring.
• @magmacomputing/tempo (Full): The "Batteries Included" version which automatically imports and registers all standard modules.

Avoid Circular Dependencies: When authoring a plugin, never import the Tempo class directly from the Full version (@magmacomputing/tempo). Doing so triggers the library's automatic registration sequence in a recursive loop, which will break your application's initialization.

Instead:

1. Use types: import type { Tempo } from '@magmacomputing/tempo/core'.
2. Use the argument: Rely on the TempoClass argument passed into your plugin function for static method access.
3. Use the engine: If you need a class reference (e.g., for instanceof checks), import only from the Lite engine (@magmacomputing/tempo/core).

---

Modern Tempo plugins are designed to be "plug-and-play." By using the defineExtension factory, a plugin registers itself with the global Tempo registry as soon as it's imported.

WARNING

Premium Plugin Example: The example below uses the @magmacomputing/tempo-plugin-ticker plugin, which is a commercial extension. You must provide a valid license key during initialization to activate it.

👉 Go to the Tempo License Registry 👈
Manage your subscriptions and retrieve your license key.

import '@magmacomputing/tempo-plugin-ticker';         // 1. Module self-registers via side-effect
import { Tempo } from '@magmacomputing/tempo/core';   // 2. Load the `lite` engine

Tempo.init({ license: 'YOUR_JWT_KEY' });              // 3. Discover, verify, and activate all imported plugins

// Ticker is now available on the core Tempo class!
const pulse = Tempo.ticker(1);

Import Order

While older versions of Tempo were sensitive to import order, current versions handle sequencing robustly. Tempo.init() is automatically called during bootstrap to ensure all discovered plugins are integrated. If you dynamically load plugins later, you can call Tempo.init() manually to refresh the registry.

---

Best Practices

1. Selective Immobility

The core methods of Tempo (like add, set, format) are protected. The extend() system will prevent you from accidentally overwriting these essential behaviors. By standardizing plugins through the Tempo module system, the entire library remains small and fast, while offering unbounded domain-specific customization.

2. Immutability

When adding instance methods that "modify" the date, always follow the Tempo pattern of returning a new instance. Use the provided factory function to wrap the resulting Temporal object back into a Tempo instance.

3. Namespace Respect

When adding many related methods, consider grouping them under a single property (e.g., tempo.term.xyz or tempo.it.abc) to keep the root Tempo interface clean and avoid collisions with future core updates.

4. Extending Core Registries

As of v2.0.1, Tempo's core registries (NUMBER, TIMEZONE, FORMAT) are protected by a Soft Freeze layer. You cannot directly assign new values to them (e.g., Tempo.TIMEZONE.myZone = '...' will fail).

Instead, use Tempo.extend() to add new data. This is the only supported way to add custom options, formats, or several timezone aliases at once.

Tempo.extend({
  timeZones: { 'UTC+13': 'Pacific/Auckland' },
  registry: { formats: { 'myCode': '{yy}{mm}{dd}' } }
});

Using Tempo.extend() ensures that the library safely bypasses the "Soft Freeze" protection and that all internal caches (like the Master Guard) are correctly synchronized.

5. Error Handling & The Diagnostic Engine

When building plugins that perform complex parsing or logic, follow Tempo's "Fail-fast by Default" principle.

• Strict Mode (Default): If your plugin encounters a terminal error (e.g., invalid input that cannot be recovered), you should throw a descriptive error.
• Catch Mode: Respect the user's catch configuration. If this.config.catch is true, instead of throwing, you should log a warning using this.warn() and return a sensible fallback (or the original input).
• Configuration Dependencies: You are responsible for managing missing configuration keys that your plugin depends on. The core engine will not validate your plugin's specific requirements. If a required config key is missing (e.g., sphere for a Season plugin), either provide a reasonable default fallback value or warn the user explicitly using this.warn(). Do not make assumptions that lead to silent failures.

// Example within a plugin instance method
if (errorCondition) {
  const msg = `Custom Error: ${details}`;
  if (this.config.catch === true) {
    this.warn(msg);
    return this; // or a fallback value
  }
  throw new Error(msg);
}

This pattern ensures that Tempo remains robust in production environments while providing strict validation during development.

6. Term Key/Scope Collisions

If your plugin registers a Term (key and optional scope), keep both identifiers globally unique.

• Avoid reusing an existing Term key (e.g., another plugin already uses qtr).
• Avoid reusing an existing scope alias (e.g., another plugin already uses quarter).

Current behavior is not ideal for collisions: duplicate Term keys are ignored, while scope alias resolution is order-dependent and can shadow another Term. Treat collisions as unsupported and choose unique names to ensure deterministic behavior.

Advanced Pattern: Stateful Classes & Callable Proxies

For complex plugins (like the Ticker) that need to maintain internal state across multiple calls or provide both a class interface and a "shortcut" function, use the Stateful Class + Proxy pattern.

1. Define a Dedicated Types Namespace

Avoid polluting the global Tempo namespace. Instead, create a dedicated Types namespace for your plugin's internal and public signatures. This prevents "Used before declaration" errors and name-shading.

export namespace MyPluginTypes {
  export type Options = { ... }
  export interface Descriptor extends AsyncGenerator<Tempo, any> {
    doSomething(): void;
  }
  // The final public interface (callable as a function)
  export interface Instance extends Descriptor {
    (): void
  }
}

2. Implement the Logic in a Class

Use a standard class to manage your state. This keeps your logic decoupled from the Proxy and the core engine.

class MyPluginInstance implements MyPluginTypes.Descriptor {
  #self!: MyPluginTypes.Instance;
  
  bootstrap(proxy: MyPluginTypes.Instance) {
    this.#self = proxy;
    return this.#self;
  }
  // ... implement Descriptor methods ...
}

3. Wrap with a Proxy in the Factory

Use a Proxy in your defineExtension factory to handle the callability trap. This allows your plugin to act as a function (the shortcut) and an object (the stateful class) simultaneously.

export const MyPlugin = defineExtension({
  name: 'MyPlugin',
  install(TempoClass: any) {
    TempoClass.myTool = function(arg1: any): MyPluginTypes.Instance {
      const instance = new MyPluginInstance(arg1);
    
    const proxy = new Proxy((() => instance.doSomething()) as any, {
      get: (_, prop) => {
        // Map proxy properties to instance methods
        if (prop in instance) return (instance as any)[prop].bind(instance);
        return (instance as any)[prop];
      },
      apply: (target) => target()
    }) as unknown as MyPluginTypes.Instance;

    return instance.bootstrap(proxy);
  };
});

---

Distributing Your Plugin

To make your plugin available to the community, package it as a standard NPM module.

Plugin Factories (with Options)

If your plugin requires its own configuration, export a factory function that returns the Tempo.Plugin function. This is the cleanest pattern for "marketplace" plugins.

// tempo-plugin-holiday/index.ts
import { defineModule } from '@magmacomputing/tempo/plugin-api';

export const HolidayModule = (pluginOptions = {}) => {
  return defineModule((TempoClass, tempoOptions, factory) => {
    // ... use pluginOptions here ...
  });
};

The Module Aggregator Pattern

If your plugin provides multiple related components (like the TermsModule), wrap them in an aggregator module to provide a uniform activation experience for the user.

// index.ts
import { defineModule } from '@magmacomputing/tempo/plugin-api';
import { PluginA } from './plugin.a.js';
import { PluginB } from './plugin.b.js';

export const MyFeatureModule = defineModule((TempoClass, options) => {
  TempoClass.extend([PluginA, PluginB]);
});

Commercial & Premium Plugins

If you have built a powerful plugin and wish to distribute it commercially, you do not need to implement your own licensing engine. Build your plugin using the standard defineModule or defineExtension wrappers.

Once your plugin is ready for the marketplace, Contact Magma Computing Solutions. We can inject our proprietary licensing and cryptographic verification engine directly into your build pipeline, ensuring your plugin is securely gated and protected from unauthorized use.

Safely Loading Premium Plugins

When using a commercially licensed premium plugin, the cryptographic verification of your license key happens securely in the background. Because of this, you should always wait for the validation engine to settle before executing premium features, especially during application boot.

Use Tempo.ready() to safely wait for the cryptographic engine:

import { Tempo } from '@magmacomputing/tempo';
import { PremiumPlugin } from 'tempo-plugin-premium';

// 1. Initialize Tempo with your license key
Tempo.init({ 
  license: process.env.TEMPO_LICENSE,
  plugins: [PremiumPlugin] 
});

async function boot() {
  // 2. Wait for the background engine to verify the signature
  await Tempo.ready();
  
  // 3. 100% safe to execute the premium plugin synchronously
  const result = Tempo.premiumFeature();
}

---

Consuming a Plugin

For developers using your extension, the process should be as simple as a single import and one call to extend().

import { Tempo } from '@magmacomputing/tempo';
import { HolidayPlugin } from 'tempo-plugin-holiday';

// Initialize the plugin with its own options and register it with Tempo
Tempo.extend(HolidayPlugin({ 
  region: 'US-NY' 
}));

---

Bulk Registration

Tempo.extend() supports rest parameters and arrays, allowing you to register multiple plugins in a single call. If the last argument is a plain object (and not a plugin/term), it is treated as a shared configuration for all plugins in that batch.

// Mix and match arrays and individual arguments
Tempo.extend(
  [PluginA, PluginB], 
  PluginC, 
  { debug: 5 } // applied to A, B, and C
);

---

🤝 Need Help Writing a Plugin?

If you have a complex business requirement or need a high-performance plugin built to professional standards, we can help. Our team can design, implement, and verify custom Tempo extensions tailored to your specific domain.

Contact Magma Computing Solutions to discuss your requirements.

• Extension Plugin Guide: Learn the "Tempo-way" to write a prototype extension (like Business Days).
• Tempo Terms Guide: Documentation on the "Memoized Lookup" pattern for business logic.