Skip to main content

Types API

This reference covers all TypeScript types and interfaces provided by mod-engine for building type-safe modification systems.

Core Configuration Types​

ConfigSpec​

The fundamental configuration interface that defines the entire system.

interface ConfigSpec {
  readonly metrics: readonly string[];
  readonly operations: readonly string[];
  readonly attributes: readonly AttributeSchema[];
}

Example​

const config: ConfigSpec = {
  metrics: ["Health", "Damage", "Defense"] as const,
  operations: ["sum", "multiply", "subtract"] as const,
  attributes: [
    { key: "Rarity", kind: "enum", values: ["Common", "Epic"] as const },
  ] as const,
};

Attribute Schema Types​

AttributeSchema​

Base interface for all attribute definitions.

interface AttributeSchema {
  readonly key: string;
  readonly kind: "enum" | "number" | "boolean" | "string";
}

EnumAttributeSchema​

Defines attributes with a fixed set of values.

interface EnumAttributeSchema {
  readonly key: string;
  readonly kind: "enum";
  readonly values: readonly string[];
  readonly cardinality?: "single" | "multi";
}

Example​

{
  key: "Rarity",
  kind: "enum",
  values: ["Common", "Rare", "Epic", "Legendary"] as const,
  cardinality: "single" // default
}

{
  key: "Tags",
  kind: "enum",
  values: ["Weapon", "Armor", "Accessory"] as const,
  cardinality: "multi" // allows multiple values
}

NumberAttributeSchema​

Defines numeric attributes with optional constraints.

interface NumberAttributeSchema {
  readonly key: string;
  readonly kind: "number";
  readonly min?: number;
  readonly max?: number;
  readonly integer?: boolean;
}

Example​

{
  key: "Level",
  kind: "number",
  min: 1,
  max: 100,
  integer: true
}

{
  key: "CritChance",
  kind: "number",
  min: 0,
  max: 100
}

BooleanAttributeSchema​

Defines true/false attributes.

interface BooleanAttributeSchema {
  readonly key: string;
  readonly kind: "boolean";
}

Example​

{
  key: "Enchanted",
  kind: "boolean"
}

StringAttributeSchema​

Defines text attributes with optional validation.

interface StringAttributeSchema {
  readonly key: string;
  readonly kind: "string";
  readonly minLen?: number;
  readonly maxLen?: number;
  readonly pattern?: string;
}

Example​

{
  key: "ItemName",
  kind: "string",
  minLen: 1,
  maxLen: 50,
  pattern: "^[A-Za-z0-9 ]+$"
}

Item Types​

ItemSpec​

Complete item specification with attributes and modifiers.

interface ItemSpec<C extends ConfigSpec> {
  readonly name?: string;
  readonly attributes: Attributes<C>;
  readonly modifiers: readonly Modifier<C>[];
}

Attributes​

Type-safe attributes object based on configuration.

type Attributes<C extends ConfigSpec> = {
  [K in AttrKeyOf<C>]?: AttrValueOf<C, K>;
};

Modifier​

Individual modifier specification.

interface Modifier<C extends ConfigSpec> {
  readonly metric: MetricOf<C>;
  readonly operation: OperationOf<C>;
  readonly value: number;
  readonly conditions?: Condition<C>;
  readonly stacking?: Stacking;
  readonly priority?: number;
  readonly source?: string;
}

Evaluation Types​

EvaluationResult​

Result of item evaluation with metrics and application trace.

interface EvaluationResult<C extends ConfigSpec> {
  readonly metrics: Record<MetricOf<C>, number>;
  readonly applied: readonly ModifierApplication<C>[];
}

ModifierApplication​

Record of a modifier application with before/after values.

interface ModifierApplication<C extends ConfigSpec> {
  readonly modifier: Modifier<C>;
  readonly appliedValue: number;
  readonly before: number;
  readonly after: number;
  readonly resultingValue: number; // deprecated alias for `after`
}

EvalContext​

Context passed to operation implementations.

interface EvalContext<C extends ConfigSpec> {
  readonly item: ItemSpec<C>;
  readonly modifier: Modifier<C>;
  readonly currentMetrics: Record<MetricOf<C>, number>;
}

Condition Types​

Condition​

Conditional logic for modifier application.

type Condition<C extends ConfigSpec> = SimpleCondition<C> | LogicalCondition<C>;

SimpleCondition​

Basic attribute comparison conditions.

type SimpleCondition<C extends ConfigSpec> =
  | { op: "eq"; attr: AttrKeyOf<C>; value: AttrValueOf<C, any> }
  | { op: "gt" | "gte" | "lt" | "lte"; attr: AttrKeyOf<C>; value: number }
  | { op: "in"; attr: AttrKeyOf<C>; values: AttrValueOf<C, any>[] }
  | { op: "includes"; attr: AttrKeyOf<C>; value: AttrValueOf<C, any> };

LogicalCondition​

Logical operators for combining conditions.

type LogicalCondition<C extends ConfigSpec> =
  | { op: "and"; clauses: Condition<C>[] }
  | { op: "or"; clauses: Condition<C>[] }
  | { op: "not"; clause: Condition<C> };

Operation Types​

OperationImpl​

Function signature for operation implementations.

type OperationImpl<C extends ConfigSpec> = (
  currentValue: number,
  modifierValue: number,
  context: EvalContext<C>
) => number;

OperationInfo​

Operation with metadata.

interface OperationInfo<C extends ConfigSpec> {
  readonly impl: OperationImpl<C>;
  readonly precedence: number;
}

BuiltinOperation​

Union of built-in operation names.

type BuiltinOperation = "sum" | "subtract" | "multiply";

Utility Types​

MetricOf​

Extracts metric names from configuration.

type MetricOf<C extends ConfigSpec> = C["metrics"][number];

Example​

type Config = typeof myConfig;
type Metrics = MetricOf<Config>; // "Health" | "Damage" | "Defense"

OperationOf​

Extracts operation names from configuration.

type OperationOf<C extends ConfigSpec> = C["operations"][number];

Example​

type Operations = OperationOf<Config>; // "sum" | "multiply" | "pow"

AttrKeyOf​

Extracts attribute keys from configuration.

type AttrKeyOf<C extends ConfigSpec> = C["attributes"][number]["key"];

Example​

type AttributeKeys = AttrKeyOf<Config>; // "Rarity" | "Level" | "Enchanted"

AttrValueOf​

Extracts attribute value type for a specific key.

type AttrValueOf<C extends ConfigSpec, K extends AttrKeyOf<C>> =
  // Complex conditional type that returns the correct value type

Example​

type RarityValue = AttrValueOf<Config, "Rarity">; // "Common" | "Rare" | "Epic"
type LevelValue = AttrValueOf<Config, "Level">; // number
type EnchantedValue = AttrValueOf<Config, "Enchanted">; // boolean

Validation Types​

ValidationResult​

Result of validation operations.

interface ValidationResult {
  readonly ok: boolean;
  readonly errors: ValidationError[];
}

ValidationError​

Detailed validation error information.

interface ValidationError {
  readonly message: string;
  readonly path?: string;
  readonly code?: string;
}

Stacking Types​

Stacking​

Modifier stacking behavior.

type Stacking = "stack" | "unique" | { uniqueBy: string };
  • "default" - All modifiers apply normally
  • "unique" - Only one modifier per source applies

Serialization Types​

SerializedData​

Generic serialized data container.

interface SerializedData<T> {
  readonly version: number;
  readonly data: T;
}

Engine Types​

Engine​

Main engine interface with core functionality.

interface Engine<C extends ConfigSpec> {
  builder(name?: string): Builder<C>;
  evaluate(
    item: ItemSpec<C>,
    options?: { base?: Partial<Record<MetricOf<C>, number>> }
  ): EvaluationResult<C>;
  validateItem(item: ItemSpec<C>): ValidationResult;
  registerOperation?(
    name: string,
    impl: OperationImpl<C>,
    options?: { precedence?: number }
  ): void;
}

Type Guards and Helpers​

Type-Safe Attribute Access​

function getAttributeValue<C extends ConfigSpec, K extends AttrKeyOf<C>>(
  attributes: Attributes<C>,
  key: K
): AttrValueOf<C, K> | undefined {
  return attributes[key];
}

Builder Helpers​

function applyAttributes<C extends ConfigSpec>(
  builder: Builder<C>,
  attributes: Partial<Attributes<C>>
): Builder<C> {
  Object.entries(attributes).forEach(([key, value]) => {
    if (value !== undefined) {
      builder.set(key as AttrKeyOf<C>, value);
    }
  });
  return builder;
}

Type Inference Examples​

// Configuration inference
const config = defineConfig({
  metrics: ["Health", "Damage"] as const,
  operations: ["sum", "multiply"] as const,
  attributes: [
    { key: "Rarity", kind: "enum", values: ["Common", "Epic"] as const },
  ] as const,
});

type Config = typeof config;
type Metrics = MetricOf<Config>; // "Health" | "Damage"
type Operations = OperationOf<Config>; // "sum" | "multiply"
type RarityValues = AttrValueOf<Config, "Rarity">; // "Common" | "Epic"

// Engine inference
const engine = createEngine(config);
type Engine = typeof engine; // Engine<Config>

// Builder inference
const builder = engine.builder("Test");
type Builder = typeof builder; // Builder<Config>

This type system ensures complete compile-time safety while maintaining flexibility for complex item modification systems.

Context added by Giga data-models - using core data model implementations, item specification model, and metric modifier model information.