@actualwave/type-checker-levels-storage

Type information storage for @actualwave/type-checkers. Stores the set of types ever observed for each property and controls how much type history to retain via reporting levels.

Installation

npm install @actualwave/type-checker-levels-storage

Reporting levels

A reporting level determines what type information is stored for a property.

| Constant | Value | Description | |---|---|---| | REPORT_ALL_ASSIGNED_TYPES | 'all' | Accumulate every distinct type ever assigned — each new type is reported once | | REPORT_FIRST_TYPE_ONLY | 'first' | Record only the first observed type — every subsequent mismatch is reported | | REPORT_NEVER | 'never' | Do not store any type information |

The global default is REPORT_FIRST_TYPE_ONLY.

Usage

Creating a storage

import { createTypesStorage } from '@actualwave/type-checker-levels-storage';

const storage = createTypesStorage();

Adding type observations

import {
  createTypesStorage,
  REPORT_ALL_ASSIGNED_TYPES,
  REPORT_FIRST_TYPE_ONLY,
} from '@actualwave/type-checker-levels-storage';

const storage = createTypesStorage<string, string>();

storage.add('count', 'number', REPORT_ALL_ASSIGNED_TYPES);
storage.add('count', 'string', REPORT_ALL_ASSIGNED_TYPES); // second type stored too

storage.add('label', 'string', REPORT_FIRST_TYPE_ONLY);
storage.add('label', 'number', REPORT_FIRST_TYPE_ONLY);    // ignored — first type wins

Checking stored types

storage.has('count');        // true
storage.get('count');        // Set { 'number', 'string' }
storage.has('unknown');      // false

Per-target reporting levels

Set reporting levels on individual objects or per-property:

import {
  setReportingLevel,
  getReportingLevel,
  REPORT_ALL_ASSIGNED_TYPES,
  REPORT_FIRST_TYPE_ONLY,
  REPORT_NEVER,
} from '@actualwave/type-checker-levels-storage';

const obj = { id: 1, label: 'hello', internal: null };

setReportingLevel(obj, REPORT_ALL_ASSIGNED_TYPES, {
  label: REPORT_FIRST_TYPE_ONLY, // override for this property
  internal: REPORT_NEVER,        // never track 'internal'
});

getReportingLevel(obj, 'id');       // 'all'
getReportingLevel(obj, 'label');    // 'first'
getReportingLevel(obj, 'internal'); // 'never'

Level resolution priority (highest to lowest):

1. Per-property level on the instance
2. Object-level on the instance
3. Per-property level on the constructor
4. Object-level on the constructor
5. Global default

Adding observations via a target object

addFor and setFor automatically resolve the level from the target object:

storage.addFor('label', 'string', obj);  // uses getReportingLevel(obj, 'label')
storage.setFor('label', types, obj);

Global reporting level

import {
  setGlobalReportingLevel,
  getGlobalReportingLevel,
  REPORT_ALL_ASSIGNED_TYPES,
} from '@actualwave/type-checker-levels-storage';

setGlobalReportingLevel(REPORT_ALL_ASSIGNED_TYPES);

Merging storages

Copy all entries from one storage into another with copyTo(). When both storages contain the same key a merge strategy resolves the conflict:

import { createTypesStorage, defaultMergeStrategy } from '@actualwave/type-checker-levels-storage';

sourceStorage.copyTo(targetStorage);

// Custom merge strategy: keep only types present in both sets (intersection)
sourceStorage.copyTo(targetStorage, obj, (key, target, source) => {
  source.forEach((type) => {
    if (!target.has(type)) target.delete(type);
  });
  return target;
});

The defaultMergeStrategy performs a union — all types from the source are added to the target.

API reference

Storage — TypeInfoStorage<K, T>

Created via createTypesStorage<K, T>().

| Method | Description | |---|---| | add(key, type, level?) | Record a type observation; level defaults to REPORT_ALL_ASSIGNED_TYPES | | addFor(key, type, target) | Like add() but resolves the level from target | | set(key, types, level?) | Replace the stored type set for a key | | setFor(key, types, target) | Like set() but resolves the level from target | | has(key) | Returns true if any types are stored for key | | get(key) | Returns the Set of stored types for key | | remove(key) | Delete all type data for key | | clone() | Return a deep copy of the storage | | copyTo(storage, target?, mergeStrategy?) | Merge this storage into storage |

Levels

| Function | Description | |---|---| | setGlobalReportingLevel(level) | Change the global default level | | getGlobalReportingLevel() | Read the global default level | | setReportingLevel(target, level, perPropertyLevels?) | Attach levels to a target object | | getReportingLevel(target, key) | Resolve the effective level for a property |

License

MIT