quickmodel / IQConfig

Interface: IQConfig

Properties

defaults?

optional defaults?: object

Default options applied to all models decorated with @Quick. Can be overridden by individual @Quick decorators.

coercionStrategy?

optional coercionStrategy?: "strict" | "loose"

Type coercion strategy.

• strict: Throws error on type mismatch (default).
• loose: Attempts strict coercion (string "123" -> number 123, "true" -> true).

dateStrategy?

optional dateStrategy?: "iso" | "timestamp" | "native"

Serialization strategy for Date objects.

• iso: Serializes to ISO 8601 string (default).
• timestamp: Serializes to numeric timestamp (ms).
• native: Keeps as Date object.

enableDebugLogs?

optional enableDebugLogs?: boolean

Enables internal debug logging (legacy shorthand — equivalent to trace.verbosity: 'debug'). Prefer using trace for fine-grained control.

exposeUnsetFields?

optional exposeUnsetFields?: boolean

If true, undefined/null values are exposed in serialized output.

Default

false

integrityErrorStrategy?

optional integrityErrorStrategy?: "failFast" | "accumulate"

Strategy for reporting integrity errors.

• 'failFast': Throws on first error.
• 'accumulate': Collects all errors (Default).

maxArrayLength?

optional maxArrayLength?: number

Global limit for array length during deserialization to prevent DoS attacks.

Default

10000

maxRecursionDepth?

optional maxRecursionDepth?: number

Limits the depth of nested objects during deserialization to prevent Stack Overflow attacks.

Default

50

normalization?

optional normalization?: object

String normalization options.

normalization.emptyStringAsNull?

optional emptyStringAsNull?: boolean

If true, converts empty strings "" to null. Default: false.

normalization.trimStrings?

optional trimStrings?: boolean

If true, applies .trim() to all string values. Default: false.

nullToUndefined?

optional nullToUndefined?: boolean

If true, converts all null values to undefined during population. Useful for standardizing missing values.

Default

false

performance?

optional performance?: object

Performance optimization settings.

performance.disableSafetyChecks?

optional disableSafetyChecks?: boolean

Disables redundant runtime safety checks (like Object.freeze) when data source is trusted. Use with caution.

Default

false

spoofMethod?

optional spoofMethod?: IQSpoofMethod

HTTP method to spoof via a _method field in toFormData() output.

Global fallback — overridden by the decorator-level option and by the toFormData({ spoofMethod }) call-time option.

Supports all RFC 7231 verbs, WebDAV (RFC 4918), DeltaV (RFC 3253), and any custom string method.

See

IQSpoofMethod

stripInternalIdentifiers?

optional stripInternalIdentifiers?: boolean | string[]

Automatically excludes properties starting with _ or $ from serialization (output), preventing internal state leakage.

• true: Strips properties starting with _ or $.
• string[]: Strips properties starting with propertys in the custom array prefix

trace?

optional trace?: object

Structured trace / observability configuration for QuickModel.

Controls which lifecycle events emit console output and at what level of detail. All settings are opt-in — no overhead when omitted.

Example

QConfig.configure({
  defaults: {
    trace: {
      verbosity: 'verbose',
      prefix: 'MyApp',
      events: ['deserialize', 'rule-fail'],
    }
  }
});

trace.colorize?

optional colorize?: IQTraceColorize

Controls which segments of the log line receive color when colors is active.

The line format is: [QM][WARN][UserModel:field][rule-fail] message

• 'level' (default) — only [LEVEL] is colored: [QM][WARN][UserModel][rule-fail]
• 'line' — the full prefix in one color block: [QM][WARN][UserModel][rule-fail]
• IQTraceColorizeSegment[] — pick exact segments: ['level', 'event'] → [QM][WARN][UserModel][rule-fail]

Default

'level'

Example

QConfig.configure({ defaults: { trace: { verbosity: 'info', colorize: ['level', 'event'] } } });

trace.colors?

optional colors?: boolean

Whether to colorize console output using ANSI escape codes.

Each log level gets a distinct color:

• error → red
• warn → bright yellow (orange-ish)
• info → light blue
• debug → purple / magenta
• verbose → gray

When omitted, colors are auto-detected from process.stdout.isTTY (enabled in interactive terminals, disabled in CI/pipes automatically).

Set false to force plain text output, true to force colors even in non-TTY environments.

Example

QConfig.configure({ defaults: { trace: { verbosity: 'info', colors: false } } });

trace.events?

optional events?: IQTraceEvent[]

Filter which lifecycle events to trace. When omitted, all events matching verbosity are traced.

Available events:

• 'construction' — model instance created (new MyModel(data))
• 'serialize' — model.$qSerialize() called
• 'deserialize' — data hydration per field
• 'rule-pass' — a @QRule predicate returned true
• 'rule-fail' — a @QRule predicate returned false
• 'rule-error' — a @QRule predicate threw an exception
• 'rule-timeout' — an async @QRule timed out
• 'integrity' — $qCheckIntegrity() result per field
• 'transformer' — which transformer was applied to each field
• 'config-change' — QConfig.configure() called

trace.prefix?

optional prefix?: string

Prefix shown in all console trace messages.

Useful when embedding QuickModel in a larger application and you want trace output tagged with your application name.

Example

QConfig.configure({ defaults: { trace: { prefix: 'MyApp' } } });
// → [MyApp][INFO][UserModel][construction] Instance created...

Default

'QM'

trace.sink?

optional sink?: (entry) => void

Custom sink for trace entries. When provided, all trace records are forwarded here instead of console. Useful for structured logging, telemetry, or test assertions.

Parameters

entry

IQTraceEntry

The structured trace record

Returns

void

trace.verbosity?

optional verbosity?: IQTraceVerbosity

Minimum log level to emit.

• 'silent' — no output at all (default when trace is omitted)
• 'error' — only hard failures (thrown errors)
• 'warn' — recoverable anomalies + errors
• 'info' — lifecycle milestones (construction, serialize, deserialize)
• 'debug' — field-level transformation steps
• 'verbose' — everything including raw input/output values per field

Default

'silent'

transformCase?

optional transformCase?: object

Case transformation strategy.

transformCase.in?

optional in?: "snake_case" | "camelCase" | "kebab-case" | "PascalCase"

transformCase.out?

optional out?: "snake_case" | "camelCase" | "kebab-case" | "PascalCase"

unknownPropertyPolicy?

optional unknownPropertyPolicy?: "error" | "keep" | "strip"

Defines behavior when encountering properties in the input payload that are not defined in the model.

• strip: Silently removes extra properties (Default).
• keep: Preserves extra properties.
• error: Throws an error.

validationTrigger?

optional validationTrigger?: "manual" | "construction"

When to run validation.

• 'manual': Must be called explicitly (Default).
• 'construction': Runs automatically on model creation.

---

history?

optional history?: object

Global history trail defaults.

Applies to every model that does not provide its own @Quick({}, { history }) config. Class-level config takes precedence over this global default.

enabled?

optional enabled?: boolean

Whether history recording is active globally. Default: false.

maxEntries?

optional maxEntries?: number

Maximum number of history entries to retain per instance. Default: 500.

recordMode?

optional recordMode?: "operation" | "field"

Recording granularity: 'operation' (one entry per call, default) or 'field' (one entry per changed field).

Example

QConfig.configure({
  history: { enabled: false, maxEntries: 500 },
});

---

i18n?

optional i18n?: object

Internationalization (i18n) settings for validation messages.

When a resolver is provided, every validation error message emitted by $qCheckRules() or $qCheckRulesAsync() is passed through it before being returned to the caller. This allows keys like 'validation.name.minLength' to be translated to the user's active locale.

resolver?

optional resolver?: (key) => string

A function that receives a message key (or raw message string) and returns the translated string for the active locale.

Called only when a rule fails — never called for passing rules.

Parameters

key

string

The raw message string or i18n key defined in @QRule().

Returns

string

The translated string (or the original key as fallback).

Example

QConfig.configure({
  i18n: {
    resolver: (key) => t(key), // pass to your i18n library
  },
});