Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
// SPDX-License-Identifier: AGPL-3.0-only
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.
// Reorder-quantity sizing used by the MRP engine (@carbon/planning) when it
// writes Order / Make planning actions; the planning pages list those actions
// rather than sizing again. The math mirrors the SQL
// `calculate_quantity_to_order` (20260324120000_planning-quantity-to-order.sql).
// A parity test pins this module against hand-computed SQL results
// (planning-sizing.test.ts) — do NOT "improve" the math here without updating
// the SQL copy too.
//
// Pure and clock-free: `todayDate` is injected by the caller
// (datetime.today(companyTimeZone)) so this module never reads a timezone. No
// React, no DB, no app imports.
import { RoundingMode, round } from "@carbon/database/precision";
import { parseDate } from "@internationalized/date";
export type PlanningSizingParams = {
reorderPoint: number;
reorderQuantity: number;
minimumOrderQuantity: number;
maximumOrderQuantity: number;
orderMultiple: number;
lotSize: number;
maximumInventoryQuantity: number;
demandAccumulationPeriod: number;
demandAccumulationSafetyStock: number;
leadTime: number;
};
export type PlanningOrderSuggestion = {
periodId: string;
startDate: string;
dueDate: string;
quantity: number;
isASAP: boolean;
policyName: string;
triggerValues: {
projectedStock?: number;
safetyStock?: number;
reorderPoint?: number;
reorderQuantity?: number;
lotSize?: number;
leadTime?: number;
};
};
export type ComputePlanningOrdersInput = {
reorderingPolicy: string;
periods: { id: string; startDate: string }[];
/** Per-period projected on-hand (week1..weekN), same order as `periods`. */
projections: number[];
/** ISO calendar date (YYYY-MM-DD). Caller supplies "today" — keeps this pure. */
todayDate: string;
params: PlanningSizingParams;
};
/** Away-from-zero ceil to the next multiple (float-artifact-immune). */
const ceilToMultiple = (value: number, multiple: number): number =>
round(value / multiple, 0, RoundingMode.Up) * multiple;
/** Whole-unit ceil. */
const ceilUnits = (value: number): number => round(value, 0, RoundingMode.Up);
/** Integer floor of a non-negative integer division (a, b integers, b > 0). */
const intFloorDiv = (a: number, b: number): number => (a - (a % b)) / b;
/** Weekly planning periods. */
const DAYS_IN_PERIOD = 7;
export type PlannedOrderSplit = {
quantity: number;
/** Days after the week's first order this one is due. */
dayOffset: number;
};
/**
* One order per batch: an order larger than the batch size (`lotSize`) is
* made in full batches with the remainder last, due dates spread evenly across
* the week. A batch size of 0, or an order that fits in one batch, is one
* order. How Demand-Based Reorder splits its order.
*/
export function lotSizeBatches(
quantity: number,
lotSize: number
): PlannedOrderSplit[] {
if (!(lotSize > 0) || quantity <= lotSize) {
return [{ quantity, dayOffset: 0 }];
}
const numberOfBatches = ceilUnits(quantity / lotSize);
return Array.from({ length: numberOfBatches }, (_, batch) => ({
quantity: Math.min(lotSize, quantity - batch * lotSize),
// integer floor — mirrors the original Math.floor without a raw-rounding call
dayOffset: intFloorDiv(batch * DAYS_IN_PERIOD, numberOfBatches)
}));
}
export type OrderSizingParams = Pick<
PlanningSizingParams,
| "reorderPoint"
| "reorderQuantity"
| "minimumOrderQuantity"
| "maximumOrderQuantity"
| "orderMultiple"
| "lotSize"
>;
/** Integer floor to a multiple (float-artifact-immune). */
const floorToMultiple = (value: number, multiple: number): number =>
round(value / multiple, 0, RoundingMode.Down) * multiple;
/**
* What ONE Demand-Based Reorder order holds: the smaller of the batch size
* and the maximum order quantity (0 = no rule), floored to the order multiple
* when there is one (a multiple larger than the cap is the cap). 0: one order
* of any size.
*/
function demandBasedPerOrder(
lotSize: number,
maximumOrderQuantity: number,
orderMultiple: number
): number {
const limits = [lotSize, maximumOrderQuantity].filter((n) => n > 0);
if (limits.length === 0) return 0;
const limit = Math.min(...limits);
if (orderMultiple > 0) {
return Math.max(orderMultiple, floorToMultiple(limit, orderMultiple));
}
return limit;
}
/**
* How ONE order of a reordering policy is sized — the same rules
* `computePlanningOrders` applies, stated once so what happens after sizing
* keeps them:
* - `perOrder`: the quantity one order holds when a need takes several —
* the batch size or maximum order quantity (Demand-Based Reorder,
* `demandBasedPerOrder`), the fixed reorder quantity, or the maximum order
* quantity (Maximum Quantity). 0: one order of any size.
* - `daily`: several orders in a week fall one per day (Fixed Reorder
* Quantity, Maximum Quantity), not spread across it (batches).
* - `maximum`: the most one order may hold. 0: no limit.
* - `minimum` / `multiples`: the least an order holds, and what it is a whole
* multiple of.
*
* MRP keeps one Order / Make action per item and week, so the orders a week
* needs are summed into it; the planning pages split it back by `perOrder`
* (`splitIntoOrders`). An Increase may not grow an order past `maximum`, and
* a Decrease keeps `minimum` and `multiples` (`reducedOrderQuantity`).
* Stock Only, Manual Reorder and an unknown policy size by none of them.
*/
export function orderSizingRules(
policyName: string | null | undefined,
params: OrderSizingParams
): {
perOrder: number;
daily: boolean;
maximum: number;
minimum: number;
multiples: number[];
} {
const lotSize = Number(params.lotSize) || 0;
const maximumOrderQuantity = Number(params.maximumOrderQuantity) || 0;
const minimumOrderQuantity = Number(params.minimumOrderQuantity) || 0;
const orderMultiple = Number(params.orderMultiple) || 0;
switch (policyName) {
case "Demand-Based Reorder": {
const perOrder = demandBasedPerOrder(
lotSize,
maximumOrderQuantity,
orderMultiple
);
return {
perOrder,
daily: false,
maximum: perOrder,
minimum: minimumOrderQuantity,
multiples: [orderMultiple]
};
}
case "Fixed Reorder Quantity": {
const reorderQuantity = Number(params.reorderQuantity) || 0;
// as computePlanningOrders: no reorder quantity orders the reorder point
const fixed =
reorderQuantity > 0
? reorderQuantity
: Number(params.reorderPoint) || 0;
return {
perOrder: fixed,
daily: true,
maximum: fixed,
minimum: 0,
multiples: [fixed]
};
}
case "Maximum Quantity":
return {
perOrder: maximumOrderQuantity,
daily: true,
maximum: maximumOrderQuantity,
minimum: minimumOrderQuantity,
// as computePlanningOrders: a multiple of 1 is no rule
multiples: [orderMultiple > 1 ? orderMultiple : 0, lotSize]
};
default:
return {
perOrder: 0,
daily: false,
maximum: 0,
minimum: 0,
multiples: []
};
}
}
/**
* A week's summed Order / Make quantity split back into the orders its policy
* sizes: full orders of `perOrder` with the remainder last, one per day
* (`daily`) or spread across the week (batches).
*/
export function splitIntoOrders(
quantity: number,
rules: Pick<ReturnType<typeof orderSizingRules>, "perOrder" | "daily">
): PlannedOrderSplit[] {
const split = lotSizeBatches(quantity, rules.perOrder);
if (!rules.daily) return split;
return split.map((order, index) => ({
...order,
dayOffset: Math.min(index, DAYS_IN_PERIOD - 1)
}));
}
/**
* What an open order may be reduced to when only `required` of it is needed:
* at least the policy's minimum and a whole multiple of each of its multiples.
* Never more than `current`, the order as it stands.
*/
export function reducedOrderQuantity(
required: number,
current: number,
rules: Pick<ReturnType<typeof orderSizingRules>, "minimum" | "multiples">
): number {
let quantity = Math.max(required, rules.minimum);
for (const multiple of rules.multiples) {
if (multiple > 0) quantity = ceilToMultiple(quantity, multiple);
}
return Math.min(quantity, current);
}
export function computePlanningOrders(
input: ComputePlanningOrdersInput
): PlanningOrderSuggestion[] {
const { reorderingPolicy, periods, projections, todayDate, params } = input;
const {
demandAccumulationPeriod,
demandAccumulationSafetyStock,
leadTime,
lotSize,
maximumInventoryQuantity,
maximumOrderQuantity,
minimumOrderQuantity,
orderMultiple,
reorderPoint,
reorderQuantity
} = params;
const orders: PlanningOrderSuggestion[] = [];
if (reorderingPolicy === "Manual Reorder") return orders;
const todaysDate = parseDate(todayDate);
let orderedQuantity = 0;
switch (reorderingPolicy) {
case "Demand-Based Reorder": {
// Process periods in chunks of demandAccumulationPeriod.
//
// End-of-window sizing: only fire an order when the LAST period in the
// window dips below safety stock, and size it to lift the end-of-window
// projection back to safety. Mirrors the SQL `calculate_quantity_to_order`
// DBR branch exactly.
//
// A window of at least one week: the form refuses 0, but an import or
// an API write can store it (or null, which arrives as NaN), and a step
// of 0 never ends this loop — one such item froze the planning page.
const windowLength = Math.max(
1,
round(Number(demandAccumulationPeriod) || 1, 0, RoundingMode.Down)
);
const batches: {
periodIndex: number;
quantity: number;
projectedStock: number;
}[] = [];
for (let i = 0; i < periods.length; i += windowLength) {
const windowEnd = Math.min(i + windowLength, periods.length);
// Track first dip (for the order's trigger date) AND walk end-of-window
// projection (for sizing).
let firstDipIndex = -1;
let endOfWindowProjection = 0;
for (let j = i; j < windowEnd; j++) {
const periodProjection = projections[j] || 0;
const effective = periodProjection + orderedQuantity;
if (
firstDipIndex === -1 &&
effective < demandAccumulationSafetyStock
) {
firstDipIndex = j;
}
endOfWindowProjection = effective;
}
// Skip the window unless end-of-window is below safety.
if (endOfWindowProjection >= demandAccumulationSafetyStock) continue;
// Defensive: fall back to window start so we never emit an undated order.
if (firstDipIndex === -1) firstDipIndex = i;
const currentPeriod = periods[firstDipIndex];
if (!currentPeriod) continue;
let totalOrderQuantity = Math.max(
0,
demandAccumulationSafetyStock - endOfWindowProjection
);
// Apply lot sizing rules to the need; the maximum order quantity
// caps each order below, never the need.
totalOrderQuantity = Math.max(totalOrderQuantity, minimumOrderQuantity);
if (orderMultiple > 0) {
totalOrderQuantity = ceilToMultiple(
totalOrderQuantity,
orderMultiple
);
}
// One order per batch, each due in the week its share is needed: the
// first week the projection, with every batch before it, is still
// under safety stock. The reschedule check dates an order by the
// first demand it covers, so a batch for week 3 due in week 1 read
// as early and was deferred as soon as it was raised. A batch no
// later week needs (rounded up past the shortfall) stays with the
// one before it.
const perOrder = demandBasedPerOrder(
lotSize,
maximumOrderQuantity,
orderMultiple
);
let neededPeriod = firstDipIndex;
let orderedBefore = orderedQuantity;
for (const batch of lotSizeBatches(totalOrderQuantity, perOrder)) {
let j = neededPeriod;
while (
j < periods.length &&
(projections[j] || 0) + orderedBefore >=
demandAccumulationSafetyStock
) {
j++;
}
if (j < periods.length) neededPeriod = j;
batches.push({
periodIndex: neededPeriod,
quantity: batch.quantity,
projectedStock: endOfWindowProjection
});
orderedBefore += batch.quantity;
}
orderedQuantity += totalOrderQuantity;
}
// Batches sharing a week spread across its days in the order they were
// sized — across windows too, since a surplus batch can land in a later
// window's week — so an earlier batch is never due after a later one.
const batchesInWeek = new Map<number, number>();
for (const batch of batches) {
batchesInWeek.set(
batch.periodIndex,
(batchesInWeek.get(batch.periodIndex) ?? 0) + 1
);
}
const placedInWeek = new Map<number, number>();
for (const batch of batches) {
const period = periods[batch.periodIndex];
if (!period) continue;
const indexInWeek = placedInWeek.get(batch.periodIndex) ?? 0;
placedInWeek.set(batch.periodIndex, indexInWeek + 1);
const dueDate = parseDate(period.startDate).add({
days: intFloorDiv(
indexInWeek * DAYS_IN_PERIOD,
batchesInWeek.get(batch.periodIndex) ?? 1
)
});
const startDate = dueDate.subtract({ days: leadTime });
orders.push({
startDate: startDate.toString(),
dueDate: dueDate.toString(),
quantity: batch.quantity,
periodId: period.id,
isASAP: startDate.compare(todaysDate) < 0,
policyName: "Demand-Based Reorder",
triggerValues: {
projectedStock: batch.projectedStock,
safetyStock: demandAccumulationSafetyStock,
lotSize,
leadTime
}
});
}
return orders;
}
case "Fixed Reorder Quantity": {
for (let i = 0; i < periods.length; i++) {
const period = periods[i];
if (!period) continue;
const projectedQuantity = projections[i] || 0;
let remainingQuantityNeeded =
reorderPoint - (projectedQuantity + orderedQuantity);
let day = 0;
let maxIterations = 100; // Safety counter
while (remainingQuantityNeeded > 0 && day < 5 && maxIterations-- > 0) {
const dueDate = parseDate(period.startDate).add({ days: day });
const startDate = dueDate.subtract({ days: leadTime });
// If reorder quantity is 0, order the same quantity as the reorder point
const orderQuantity =
reorderQuantity > 0 ? reorderQuantity : reorderPoint;
// Both left at 0 on a short item: ordering 0 covers nothing, so the
// loop emitted an "Order 0" for every short day and week. Nothing to
// size from — suggest nothing, as Maximum Quantity does.
if (orderQuantity <= 0) break;
orders.push({
startDate: startDate.toString(),
dueDate: dueDate.toString(),
quantity: orderQuantity,
periodId: period.id,
isASAP: startDate.compare(todaysDate) < 0,
policyName: "Fixed Reorder Quantity",
triggerValues: {
projectedStock: projectedQuantity + orderedQuantity,
reorderPoint,
reorderQuantity,
leadTime
}
});
day++;
orderedQuantity += orderQuantity;
remainingQuantityNeeded =
reorderPoint - (projectedQuantity + orderedQuantity);
}
}
return orders;
}
case "Maximum Quantity": {
for (let i = 0; i < periods.length; i++) {
const period = periods[i];
if (!period) continue;
const projectedQuantity = projections[i] || 0;
let remainingQuantityNeeded =
reorderPoint - (projectedQuantity + orderedQuantity);
let day = 0;
let maxIterations = 100; // Safety counter
while (remainingQuantityNeeded > 0 && day < 5 && maxIterations-- > 0) {
const dueDate = parseDate(period.startDate).add({ days: day });
const startDate = dueDate.subtract({ days: leadTime });
// Calculate required quantity up to maximum inventory
const requiredQuantity =
maximumInventoryQuantity - (projectedQuantity + orderedQuantity);
// If reorder quantity is 0, use reorder point as the base order quantity
let orderQuantity =
reorderQuantity > 0
? Math.max(minimumOrderQuantity, requiredQuantity)
: reorderPoint;
// Ensure orderQuantity is positive to prevent infinite loop
if (orderQuantity <= 0) break;
// Round to nearest multiple if specified
if (orderMultiple && orderMultiple > 1) {
orderQuantity = ceilToMultiple(orderQuantity, orderMultiple);
}
// Only apply lot size if it's greater than 0
if (lotSize > 0) {
orderQuantity = ceilToMultiple(orderQuantity, lotSize);
}
// Apply maximum order quantity only if it's greater than 0
if (maximumOrderQuantity > 0) {
orderQuantity = Math.min(orderQuantity, maximumOrderQuantity);
}
orders.push({
startDate: startDate.toString(),
dueDate: dueDate.toString(),
quantity: orderQuantity,
periodId: period.id,
isASAP:
startDate.compare(todaysDate) < 0 &&
projectedQuantity + orderedQuantity < 0,
policyName: "Maximum Quantity",
triggerValues: {
projectedStock: projectedQuantity + orderedQuantity,
reorderPoint,
leadTime,
reorderQuantity
}
});
day++;
orderedQuantity += orderQuantity;
remainingQuantityNeeded =
reorderPoint - (projectedQuantity + orderedQuantity);
}
}
return orders;
}
default:
return orders;
}
}