Writing a plugin

import { definePlugin, check, PASS, fail } from '@maroonedog/luq/plugin-kit';
import type { Unchanged } from '@maroonedog/luq/plugin-kit';

export const evenPlugin = /*#__PURE__*/ definePlugin<{
  args: readonly [];                     // what the chain method takes
  out: Unchanged;                        // what happens to the chain afterwards
  context: { readonly actual: number };  // what messageFactory receives
}>()({
  name: 'even',                  // the default error code
  method: 'even',                // what you call: b.number.even()
  slots: ['number'] as const,    // where the method appears
  build: ctx =>
    check({
      code: ctx.code,
      messageFactory: ctx.messageFactory,
      severity: ctx.severity,
      run: value =>
        typeof value !== 'number' || value % 2 === 0
          ? PASS
          : fail({ actual: value }),
      describe: (_detail, messageContext) =>
        `${messageContext.path} must be even`,
      buildMessageContext: detail => ({
        actual: typeof detail.actual === 'number' ? detail.actual : 0,
      }),
    }),
});

import { Builder } from '@maroonedog/luq';

type Basket = { count: number };

// Your plugin goes in the bag exactly like a built-in one. Nothing about the
// 77 shipped plugins is privileged; they are written against this surface.
const basketValidator = Builder()
  .use(evenPlugin)
  .for<Basket>()
  .v('count', b => b.number.even())
  .build();

interface PluginSignature {
  readonly args: readonly unknown[];  // what the chain method takes
  readonly out: unknown;              // what happens to the chain afterwards
  readonly context: object;           // what messageFactory receives
}

import { Builder } from '@maroonedog/luq';
import { definePlugin, transform } from '@maroonedog/luq/plugin-kit';
import type {
  MessageContextExtra,
  SelfReader,
  TransformOut,
} from '@maroonedog/luq/plugin-kit';

// out: TransformOut => build() must return a TransformRule, and the chain
// method gets a FIXED signature the marker imposes:
//   <R>(map: (value) => R, options?) => chain whose type is now R
const mapPlugin = /*#__PURE__*/ definePlugin<{
  args: readonly [map: SelfReader<unknown>];
  out: TransformOut;
  context: MessageContextExtra;
}>()({
  name: 'map',
  method: 'map',
  slots: ['string', 'number'] as const,
  build: (_ctx, map) => transform(value => map(value)),
});

type Signup = { email: string };

const signupValidator = Builder()
  .use(mapPlugin)
  .for<Signup>()
  .v('email', b => b.string.map(value => value.trim().length))
  .build();

// Transforms run in parse() only, and only after every check on the field
// passed — never in validate().
signupValidator.parse({ email: '  a@b.com  ' });     // data: { email: 7 }
signupValidator.validate({ email: '  a@b.com  ' });  // data: { email: '  a@b.com  ' }

import { definePlugin, presence } from '@maroonedog/luq/plugin-kit';
import type { MessageContextExtra, PresenceShift } from '@maroonedog/luq/plugin-kit';

// out: PresenceShift<'excludeMissing'> => build() must return a PresenceRule,
// and the chain's type loses undefined and null.
export const mandatoryPlugin = /*#__PURE__*/ definePlugin<{
  args: readonly [];
  out: PresenceShift<'excludeMissing'>;
  context: MessageContextExtra;
}>()({
  name: 'mandatory',
  method: 'mandatory',
  slots: ['string'] as const,
  build: ctx =>
    presence({
      code: ctx.code,
      messageFactory: ctx.messageFactory,
      severity: ctx.severity,
      allowUndefined: false,
      allowNull: false,
      emptyStringIsMissing: true,
      describe: messageContext => `${messageContext.path} is mandatory`,
      buildMessageContext: () => ({}),
    }),
});

import {
  definePlugin,
  check,
  PluginArgumentError,
  PASS,
  fail,
  isString,
} from '@maroonedog/luq/plugin-kit';
import type { Unchanged } from '@maroonedog/luq/plugin-kit';

export interface PrefixContext {
  readonly prefix: string;
  readonly actual: string;
}

export const prefixPlugin = /*#__PURE__*/ definePlugin<{
  args: readonly [prefix: string];
  out: Unchanged;
  context: PrefixContext;
}>()({
  name: 'prefix',
  method: 'prefix',
  slots: ['string'] as const,
  build: (ctx, prefix) => {
    // A bad argument is a BUILD-time error, not a check that never fires.
    if (prefix.length === 0) {
      throw new PluginArgumentError(ctx.pluginName, 'prefix', prefix);
    }
    return check({
      code: ctx.code,
      messageFactory: ctx.messageFactory,
      severity: ctx.severity,
      // A wrong-typed value PASSES. The slot guard owns type and the presence
      // rules own null/undefined; re-deciding either duplicates the issue
      // under the wrong code.
      run: value =>
        !isString(value) || value.startsWith(prefix)
          ? PASS
          : fail({ expected: prefix, actual: value }),
      describe: (_detail, messageContext) =>
        `${messageContext.path} must start with ${prefix}`,
      buildMessageContext: detail => ({
        prefix,
        actual: isString(detail.actual) ? detail.actual : '',
      }),
    });
  },
});

import { Builder } from '@maroonedog/luq';
import { requiredPlugin } from '@maroonedog/luq/plugins/required';
import { stringMinPlugin } from '@maroonedog/luq/plugins/stringMin';
import { numberMinPlugin } from '@maroonedog/luq/plugins/numberMin';
import { arrayEachPlugin } from '@maroonedog/luq/plugins/arrayEach';
import { objectPropertyNamesPlugin } from '@maroonedog/luq/plugins/objectPropertyNames';
import { objectAdditionalPropertiesSchemaPlugin } from '@maroonedog/luq/plugins/objectAdditionalProperties';
import { unionGuardPlugin } from '@maroonedog/luq/plugins/unionGuard';

type Inventory = {
  skus: string[];
  quantities: Record<string, number>;
  code: string | number;
};

const inventoryValidator = Builder()
  .use(requiredPlugin)
  .use(stringMinPlugin)
  .use(numberMinPlugin)
  .use(arrayEachPlugin)
  .use(objectPropertyNamesPlugin)
  .use(objectAdditionalPropertiesSchemaPlugin)
  .use(unionGuardPlugin)
  .for<Inventory>()
  // ElementChain — the sub-chain's subject is one ELEMENT of the array.
  .v('skus', b => b.array.each(e => e.string.required().min(4)))
  // PropertyKeyChain — the subject is the property KEY, always a string.
  .v('quantities', b => b.object.propertyNames(k => k.string.min(2)))
  // PropertyValueChain — the subject is any property VALUE.
  .v('quantities', b => b.object.additionalPropertiesSchema(v => v.number.min(0)))
  // NarrowedChain — the subject is the value NARROWED by the guard.
  // `out: GuardOut` records the covered member in the chain's state, so
  // `.build()` does not exist until every union member is covered.
  .v('code', b =>
    b.union
      .guard(
        (value): value is string => typeof value === 'string',
        narrowed => narrowed.string.min(3)
      )
      .guard(
        (value): value is number => typeof value === 'number',
        narrowed => narrowed.number.min(1)
      )
  )
  .build();

import {
  definePlugin,
  branch,
  composite,
  PASS,
  fail,
  isArray,
} from '@maroonedog/luq/plugin-kit';
import type {
  ElementChain,
  MessageContextExtra,
  Unchanged,
} from '@maroonedog/luq/plugin-kit';

export const eachPlugin = /*#__PURE__*/ definePlugin<{
  args: readonly [element: ElementChain];
  out: Unchanged;
  context: MessageContextExtra;
}>()({
  name: 'each',
  method: 'each',
  slots: ['array'] as const,
  // WHICH positions carry a sub-chain cannot be recovered once the types are
  // erased — a NarrowedChain and a RootPredicate are both plain functions —
  // so the plugin declares it.
  subChainArguments: [0],
  build: (ctx, element) =>
    composite({
      code: ctx.code,
      messageFactory: ctx.messageFactory,
      severity: ctx.severity,
      // The user's callback ran ONCE, at build() time. What arrives here is a
      // compiled rule list.
      branches: [branch('element', element)],
      combine: runners => {
        const runner = runners[0];
        if (runner === undefined) return () => PASS;
        return (value, runContext) => {
          if (!isArray(value)) return PASS;
          // This loop walks VALUES, not rules. A plugin never loops over
          // rules itself: execution lives in exactly one place, the engine.
          for (let index = 0; index < value.length; index += 1) {
            const outcome = runner.run(value[index], runContext);
            if (!outcome.ok) return fail({ ...outcome.detail, index });
          }
          return PASS;
        };
      },
      describe: detail => `Element ${String(detail.index)} failed`,
      buildMessageContext: () => ({}),
    }),
});