inventory.expiry-fefo

export function fefoPick(batches: readonly StockBatch[], quantity: number, asAt: string, minShelfLifeDays: number): FefoPick

/** Units of one batch or lot on hand. */
export interface StockBatch {
  readonly batch: string;
  /** the last day the stock may be used or sold */
  readonly expiry: string;
  /** units on hand, not negative */
  readonly quantity: number;
}

/** Units to take from one batch. */
export interface PickLine {
  readonly batch: string;
  readonly expiry: string;
  readonly quantity: number;
}

/** The pick list, and what could not be picked. */
export interface FefoPick {
  /** in pick order, earliest expiry first */
  readonly lines: readonly PickLine[];
  /** units on the list */
  readonly picked: number;
  /** units wanted but not available in date; 0 when the request is met */
  readonly shortfall: number;
  /** batches passed over as expired or too short-dated, earliest expiry first */
  readonly skipped: readonly string[];
}

import { fefoPick } from "#fune/inventory.expiry-fefo@^1";

import { daysBetween } from "./dates_days_between.ts";  ← from dates.days-between ^1.0.0 · built alongside by fune
import { type FefoPick, type PickLine, type StockBatch } from "./inventory_expiry_fefo_types.ts";

function wholeUnits(name: string, value: number): void {
  if (!Number.isInteger(value) || value < 0) {
    throw new RangeError(`${name} must be a whole number, not negative, received ${value}`);
  }
}

/**
 * Pick `quantity` units earliest expiry first, from batches with at least
 * `minShelfLifeDays` of life left on `asAt`. Short stock is a shortfall, not
 * an error.
 */
export function fefoPick(batches: readonly StockBatch[], quantity: number, asAt: string, minShelfLifeDays: number): FefoPick {
  wholeUnits("quantity", quantity);
  wholeUnits("minShelfLifeDays", minShelfLifeDays);
  const dated = batches.map((batch, index) => {
    wholeUnits(`quantity of batch "${batch.batch}"`, batch.quantity);
    return { batch, index, life: daysBetween(asAt, batch.expiry) };
  });
  // Array.prototype.sort is stable, so equal expiry dates keep their order.
  dated.sort((a, b) => a.life - b.life);
  const lines: PickLine[] = [];
  const skipped: string[] = [];
  let remaining = quantity;
  for (const { batch, life } of dated) {
    if (batch.quantity === 0) continue;
    if (life < minShelfLifeDays) {
      skipped.push(batch.batch);
      continue;
    }
    if (remaining === 0) continue;
    const take = Math.min(remaining, batch.quantity);
    lines.push({ batch: batch.batch, expiry: batch.expiry, quantity: take });
    remaining -= take;
  }
  return { lines, picked: quantity - remaining, shortfall: remaining, skipped };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 1 dependency, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add inventory.expiry-fefo

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./inventory.expiry-fefo-1.0.0-typescript.fune, or fetch it from a terminal with fune pull inventory.expiry-fefo@1.0.0:typescript.

The whole function, every language, is one file too: inventory.expiry-fefo-1.0.0.fune, 18,600 bytes, sha256 9bbf73c5c2b456aff2db9af2961110453eebfcea6ecd6ff8937a4798b3abdda0. It installs into a project of any language.

// fune: before inventory.expiry-fefo

// fune: after inventory.expiry-fefo

// fune: replace dates.days-between in inventory.expiry-fefo

// fune: step inventory.expiry-fefo after <n|label>

More from the author

**Order.** Usable batches are taken earliest expiry first; batches with the same expiry are taken in the order given (sort them by location or receipt date first if that matters). A batch is used up before the next is started, so the list has at most one part-used batch, the last.

**Not enough stock is an answer, not an error.** The list picks everything usable and reports the rest as `shortfall`, which a warehouse needs to back-order or short-ship. Batches with no units are ignored, neither picked nor skipped. Negative quantities, a negative shelf life and malformed dates are errors.

This works in whole units. It does not reserve stock, so two picks run from the same batch list will both take the same units.

Source: FEFO as described in the EU Good Distribution Practice guidelines (2013/C 343/01), section 5.5, and the GS1 General Specifications for expiry dates (AI 17).

Files