resolveWithDefaults

Utility function for merging default options with user-provided overrides

Overview

resolveWithDefaults is a shallow merge helper that combines default options with user-provided overrides, filtering out undefined values.

Function Signature

function resolveWithDefaults<T extends object>(
  defaults: T,
  overrides?: Partial<T>
): T

Parameters

defaults · T · required

The default options object containing all required fields with their default values.

overrides · Partial<T>

Optional user-provided overrides. Undefined values are filtered out, allowing explicit undefined to be distinguished from missing keys.

Returns

result · T

A new object with defaults merged with overrides. Undefined values in overrides are ignored, preserving the default values.

Usage

This utility is primarily used internally by Kokokor to merge configuration options:

import { resolveWithDefaults } from 'kokokor';

const defaults = {
  pixelTolerance: 5,
  lineHeightFactor: 0.3,
  centerToleranceRatio: 0.05
};

const userOptions = {
  pixelTolerance: 10,
  lineHeightFactor: undefined // This will be filtered out
};

const resolved = resolveWithDefaults(defaults, userOptions);
// Result: { pixelTolerance: 10, lineHeightFactor: 0.3, centerToleranceRatio: 0.05 }

Behavior

• Shallow merge: Only top-level keys are merged. Nested objects are not deeply merged.
• Undefined filtering: Undefined values in overrides are removed before merging, so they don’t overwrite default values.
• Type safety: The function is generic and preserves TypeScript type information.

For nested option objects (like poetryDetectionOptions), Kokokor handles deep merging explicitly at the call site rather than recursively.

Related

MapObservationsToTextLinesOptions

See the options types that use this utility

Advanced Configuration

Learn about configuring Kokokor