@marianmeres/topo-merge

Multiple inheritance for POJOs via topological sort and deep merge.

Installation

deno add jsr:@marianmeres/topo-merge

npm i @marianmeres/topo-merge

Quick Example

import { topoMerge } from "@marianmeres/topo-merge";

const result = topoMerge({
    a: { foo: "bar" },
    b: { __extends: "a", baz: "bat" },
    c: { __extends: "b", hey: "ho" },
    d: { __extends: "c", lets: "go", foo: "foo" },
    e: { __extends: ["b", "c"] }, // multiple inheritance
});

// Result:
// a: { foo: "bar" }
// b: { foo: "bar", baz: "bat" }
// c: { foo: "bar", baz: "bat", hey: "ho" }
// d: { foo: "foo", baz: "bat", hey: "ho", lets: "go" }
// e: { foo: "bar", baz: "bat", hey: "ho" }

API

topoMerge(schema, mergeOptions?, mergeOmitIdProp?)

Main function that resolves inheritance and merges objects.

function topoMerge(
    schema: Record<string, WithExtends> | [string, WithExtends][],
    mergeOptions?: DeepMergeOptions,
    mergeOmitIdProp?: boolean // default: true
): Record<string, Record<string, any>>

• schema - Object or entries array where keys become node IDs
• mergeOptions - Options for deepMerge. Default: { arrays: "replace" }
• mergeOmitIdProp - Whether to exclude the id property from results. Default: true

topoSort(nodes)

Lower-level utility for topological sorting. Most users should use topoMerge instead.

Merge Behavior

• Child overrides parent - Properties defined on a node override inherited ones
• Later parents override earlier - With __extends: ["a", "b"], values from b override values from a (matches Object.assign({}, a, b) intuition)
• Arrays are replaced - By default, arrays replace rather than concatenate (configurable via mergeOptions.arrays)
• Deep merge - Nested objects are recursively merged
• Explicit undefined - Set a property to undefined to remove an inherited value

Multi-parent precedence example:

topoMerge({
    a: { x: 1, y: 10 },
    b: { __extends: "a", x: 2 },   // more specific: x → 2
    c: { __extends: ["a", "b"] },  // b wins over a
});
// c → { x: 2, y: 10 }

Breaking Changes in 2.0

• Multi-parent precedence flipped. Previously, the leftmost parent in __extends won on conflicts and diamond inheritance was resolved incorrectly. Now the rightmost parent wins, and diamonds resolve as expected. If any of your schemas relied on leftmost-wins, reorder the __extends list.
• Indirect circular dependencies now throw (Circular dependency detected...) instead of overflowing the stack.
• Duplicate keys in entries-array input now throw instead of silently dropping earlier entries.
• mergeOptions is no longer mutated by topoMerge.
• Array-merge order is now deterministic (parents in __extends order, own props last).

Full API Documentation

See API.md for complete API reference including all interfaces, error handling, and detailed examples.