Skip to main content

Ephemerals

Table of Contents​

  1. Overview
  2. Key Components
  3. Methods
  4. Usage Example
  5. Conclusion

Overview​

The ephemerals.ts file provides functionality to work with temporary or "ephemeral" data extensions on objects. This can be particularly useful for scenarios where transient data needs to be associated with an object without permanently altering its structure. The file leverages the TypeTools framework to manage these extensions efficiently.

Ephemerals - Serialization Control​

Ephemerals extension will modify toJSON function of the class to make sure ephemeral properties are not serialized by JSON.stringify. (Performance cost: negligible.)

class EphemTest {
  keptProp = 'value';
  ignoredProp1 = 'test5'; /* EPHEM */
  ignoredProp2 = 5; /* EPHEM */
  constructor(init?: Partial<EphemTest>) {
    defineOn(this, EphemTest, lib => {
      lib.ephemerals.of(this, {
        ignoredProp1: true,
        ignoredProp2: true,
        ...
  }
}
console.log( JSON.stringify(new EphemTest()) ); // {"keptProp":"value"}

EphemeralsSettings​

The EphemeralsSettings class extends from TypeToolsSettings and is used to initialize settings specific to the Ephemerals extension.

  • Static Property: extensionEphemerals - A string identifier for the extension.
  • Constructor: Accepts an optional partial initialization object.
export class EphemeralsSettings extends TypeToolsSettings {
    static extensionEphemerals = 'Ephemerals';
    extensionEphemerals = EphemeralsSettings.extensionEphemerals;

    constructor(init?: Partial<EphemeralsSettings>) {
        super(init);
        if (init) {
            Object.assign(this, init);
        }
    }
}

EphemeralsExtensionData​

This class is an interface for extension data, defining a flexible structure ([prop: string]: { source: any; data: any }) to store ephemeral data associated with object properties.

export class EphemeralsExtensionData implements TypeToolsExtensionData {
    [prop: string]: { source: any; data: any };
}

Ephemerals​

The core class that implements the ephemeral extension functionality.

  • Static Properties:

    • debugData: Collects debugging information.
    • debugDataCollect: Flag to enable or disable debug data collection.

  • Methods: Various static and instance methods to manage ephemeral data.

export class Ephemerals implements TypeToolsExtension {
    static debugData: { ignoredKey: string; source: any; data?: any }[] = [];
    static debugDataCollect = false;
    // Further implementation...
}

Methods​

getExtensionData​

  • Purpose: Retrieve extension data from a target object.
  • Signature: static getExtensionData(target: any, settings = EphemeralsSettings): EphemeralsExtensionData

typeCheck​

  • Purpose: Check if a target object has the specific ephemeral extension data.
  • Signature: static typeCheck(target: any, settings = EphemeralsSettings): boolean

implementOn​

  • Purpose: Implements the ephemeral extension on a given target if it doesn't already exist.
  • Signature: static implementOn(target: any, settings = EphemeralsSettings)

of​

  • Purpose: Define ephemeral properties on a target object.
  • Signature: static of<T = any>(target: T, properties: PartialAny<T>, settings = EphemeralsSettings)

Usage Example​

Here's a simple example of how you might use the Ephemerals class to extend an object with ephemeral properties:

import { Ephemerals } from './ephemerals';

// Create a target object
let myObject = { name: 'Ephemeral Test' };

// Define ephemeral properties
const properties = {
    temporaryData: { value: 123 },
};

// Apply ephemerals to the object
Ephemerals.of(myObject, properties);

// Convert to JSON, which respects ephemeral definition
console.log(myObject.toJSON());