@mark1russell7/packing 0.1.2 → 0.1.3

package/src/frame.ts

@@ -0,0 +1,262 @@
+// The internal frame of the adapters of 0.1: the conversion of a PackInput to the Rect objects of 0.1, and back.
+// Each item grows by its margin and by half the gap on each side. Each obstacle grows by half the gap. Thus two items
+// are `mA + gap + mB` apart. The area of the frame is the container less the inset, grown by half the gap on each side.
+
+import { EPS, marginOf, type Item, type Obstacle, type PackInput, type PackOutput, type Placement, type Region, type StageTrace } from "./contract.ts";
+import { Rect } from "./rect.ts";
+
+const clock = (globalThis as { performance?: { now(): number } }).performance;
+
+/** This function gives the time in milliseconds. */
+export function now(): number {
+  return clock ? clock.now() : Date.now();
+}
+
+/** This function gives the bounding box of a region. */
+export function boundsOf(region: Region): { x: number; y: number; w: number; h: number } {
+  switch (region.kind) {
+    case "rect":
+      return { x: region.x, y: region.y, w: region.w, h: region.h };
+    case "circle":
+      return { x: region.cx - region.r, y: region.cy - region.r, w: 2 * region.r, h: 2 * region.r };
+    case "ellipse":
+      return { x: region.cx - region.rx, y: region.cy - region.ry, w: 2 * region.rx, h: 2 * region.ry };
+    case "polygon": {
+      const xs = region.points.map((p) => p[0]);
+      const ys = region.points.map((p) => p[1]);
+      const x = Math.min(...xs);
+      const y = Math.min(...ys);
+      return { x, y, w: Math.max(...xs) - x, h: Math.max(...ys) - y };
+    }
+  }
+}
+
+/** The rectangle of a container: its origin and its size. A free side has the size `Infinity`. */
+export interface Bounds {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** This function gives the rectangle of a container. A rectangle shape gives the origin and the sizes of the fixed sides. */
+export function containerBounds(input: PackInput): Bounds {
+  const { container } = input;
+  const shape = container.shape === undefined ? undefined : boundsOf(container.shape);
+  const fixedW = container.fixed === "size" || container.fixed === "width";
+  const fixedH = container.fixed === "size" || container.fixed === "height";
+  const w = shape?.w ?? container.w;
+  const h = shape?.h ?? container.h;
+  if (fixedW && w === undefined) throw new TypeError(`A container with fixed "${container.fixed}" needs a width.`);
+  if (fixedH && h === undefined) throw new TypeError(`A container with fixed "${container.fixed}" needs a height.`);
+  return { x: shape?.x ?? 0, y: shape?.y ?? 0, w: fixedW ? w! : Infinity, h: fixedH ? h! : Infinity };
+}
+
+/** One rectangle of the frame, and the item or the obstacle that it measures. */
+export interface Entry {
+  rect: Rect<number>;
+  item?: Item;
+  obstacle?: Obstacle;
+  /** The offset from the corner of the rectangle to the corner of the item or the obstacle. */
+  dx: number;
+  dy: number;
+}
+
+/** The rectangles of 0.1 for one input. */
+export interface Frame {
+  /** The container coordinates of the origin of the frame. */
+  ox: number;
+  oy: number;
+  /** The size of the area of the frame. A free side has the size `Infinity`. */
+  w: number;
+  h: number;
+  bounds: Bounds;
+  inset: number;
+  /** The items in the order of their rank, then the obstacles. */
+  entries: Entry[];
+  /** The ids of the items that are too large for the area. The frame has no rectangle for them. */
+  tooLarge: string[];
+}
+
+/** This function gives the items in the order of their rank. The index in the array is the rank of an item without one. */
+export function byRank(items: readonly Item[]): Item[] {
+  return items
+    .map((item, index) => ({ item, rank: item.rank ?? index }))
+    .toSorted((a, b) => a.rank - b.rank)
+    .map((e) => e.item);
+}
+
+/**
+ * This function makes the frame of an input. A locked item with a position and an obstacle without `move` are locked
+ * rectangles. An obstacle with `move` is a free rectangle only when `movable` is `true`.
+ */
+export function buildFrame(input: PackInput, movable = false): Frame {
+  const bounds = containerBounds(input);
+  const inset = input.container.inset ?? 0;
+  const half = (input.gap ?? 0) / 2;
+  const ox = bounds.x + inset - half;
+  const oy = bounds.y + inset - half;
+  const w = bounds.w - 2 * inset + 2 * half;
+  const h = bounds.h - 2 * inset + 2 * half;
+  const entries: Entry[] = [];
+  const tooLarge: string[] = [];
+
+  for (const item of byRank(input.items)) {
+    const m = marginOf(item);
+    const rect = new Rect<number>();
+    rect.size.set(item.w + m.left + m.right + 2 * half, item.h + m.top + m.bottom + 2 * half);
+    const dx = m.left + half;
+    const dy = m.top + half;
+    if (item.locked === true && item.x !== undefined && item.y !== undefined) {
+      rect.locked = true;
+      rect.position.set(item.x - dx - ox, item.y - dy - oy);
+    } else if (rect.size.x > w + EPS || rect.size.y > h + EPS) {
+      tooLarge.push(item.id);
+      continue;
+    }
+    entries.push({ rect, item, dx, dy });
+  }
+
+  for (const obstacle of input.obstacles ?? []) {
+    const b = boundsOf(obstacle.region);
+    const rect = new Rect<number>();
+    rect.size.set(b.w + 2 * half, b.h + 2 * half);
+    rect.position.set(b.x - half - ox, b.y - half - oy);
+    rect.locked = !(movable && obstacle.move !== undefined);
+    entries.push({ rect, obstacle, dx: half, dy: half });
+  }
+  return { ox, oy, w, h, bounds, inset, entries, tooLarge };
+}
+
+/** This function gives the outer rectangle of 0.1 for a frame. A free height starts at 0 and grows. */
+export function outerOf(frame: Frame): Rect<number> {
+  const outer = new Rect<number>();
+  const fixedSize = Number.isFinite(frame.h);
+  outer.size.set(frame.w, fixedSize ? frame.h : 0);
+  outer.fixedWidth = true;
+  outer.fixedSize = fixedSize;
+  return outer;
+}
+
+/** This function gives the rectangles of a frame, in the order of the entries. */
+export function rectsOf(frame: Frame): Rect<number>[] {
+  return frame.entries.map((e) => e.rect);
+}
+
+/**
+ * This function reads the output from the rectangles of a frame after a packing of 0.1. A locked item keeps its
+ * position exactly. Each other item that the packer did not place goes to the overflow.
+ */
+export function readFrame(input: PackInput, frame: Frame, trace: StageTrace[], moved: PackOutput["moved"] = []): PackOutput {
+  const placements: Placement[] = [];
+  const overflow: string[] = [...frame.tooLarge];
+  for (const e of frame.entries) {
+    const item = e.item;
+    if (item === undefined) continue;
+    if (item.locked === true && item.x !== undefined && item.y !== undefined) placements.push({ id: item.id, x: item.x, y: item.y });
+    else if (e.rect.wasPacked) placements.push({ id: item.id, x: e.rect.position.x + e.dx + frame.ox, y: e.rect.position.y + e.dy + frame.oy });
+    else overflow.push(item.id);
+  }
+  return { placements, overflow, size: sizeOf(input, frame, placements, moved), moved, trace };
+}
+
+/**
+ * This function gives the size of the container after a packing. A fixed side keeps its size. A free side goes to the
+ * far edge of the items with their margins and the inset, or of the obstacles.
+ */
+function sizeOf(input: PackInput, frame: Frame, placements: Placement[], moved: PackOutput["moved"]): { w: number; h: number } {
+  const items = new Map(input.items.map((i) => [i.id, i]));
+  let right = 0;
+  let bottom = 0;
+  for (const p of placements) {
+    const item = items.get(p.id)!;
+    const m = marginOf(item);
+    right = Math.max(right, p.x + item.w + m.right + frame.inset - frame.bounds.x);
+    bottom = Math.max(bottom, p.y + item.h + m.bottom + frame.inset - frame.bounds.y);
+  }
+  const movedById = new Map(moved.map((m) => [m.id, m]));
+  for (const o of input.obstacles ?? []) {
+    const b = boundsOf(o.region);
+    const at = movedById.get(o.id) ?? b;
+    right = Math.max(right, at.x + b.w - frame.bounds.x);
+    bottom = Math.max(bottom, at.y + b.h - frame.bounds.y);
+  }
+  return {
+    w: Number.isFinite(frame.bounds.w) ? frame.bounds.w : right,
+    h: Number.isFinite(frame.bounds.h) ? frame.bounds.h : bottom,
+  };
+}
+
+/** This function gives a region with the axes changed: x for y, and w for h. */
+export function transposeRegion(region: Region): Region {
+  switch (region.kind) {
+    case "rect":
+      return { kind: "rect", x: region.y, y: region.x, w: region.h, h: region.w };
+    case "circle":
+      return { kind: "circle", cx: region.cy, cy: region.cx, r: region.r };
+    case "ellipse":
+      return { kind: "ellipse", cx: region.cy, cy: region.cx, rx: region.ry, ry: region.rx };
+    case "polygon": {
+      const swap = (ring: [number, number][]): [number, number][] => ring.map(([x, y]) => [y, x]);
+      const turned: Region = { kind: "polygon", points: swap(region.points) };
+      if (region.holes) turned.holes = region.holes.map(swap);
+      return turned;
+    }
+  }
+}
+
+/** This function gives an item with the axes changed. The ports go, because the adapters of 0.1 do not read them. */
+function transposeItem(item: Item): Item {
+  const { ports: _ports, ...rest } = item;
+  const turned: Item = { ...rest, w: item.h, h: item.w };
+  delete turned.x;
+  delete turned.y;
+  if (item.y !== undefined) turned.x = item.y;
+  if (item.x !== undefined) turned.y = item.x;
+  if (item.shape) turned.shape = transposeRegion(item.shape);
+  if (item.margin !== undefined && typeof item.margin !== "number") {
+    const m = item.margin;
+    turned.margin = { top: m.left, right: m.bottom, bottom: m.right, left: m.top };
+  }
+  return turned;
+}
+
+/** This function gives an input with the axes changed. A fixed height becomes a fixed width. */
+export function transposeInput(input: PackInput): PackInput {
+  const c = input.container;
+  const container: PackInput["container"] = { fixed: c.fixed === "height" ? "width" : c.fixed === "width" ? "height" : c.fixed };
+  if (c.h !== undefined) container.w = c.h;
+  if (c.w !== undefined) container.h = c.w;
+  if (c.aspect !== undefined) container.aspect = 1 / c.aspect;
+  if (c.aspectWeight !== undefined) container.aspectWeight = c.aspectWeight;
+  if (c.shape !== undefined) container.shape = transposeRegion(c.shape);
+  if (c.inset !== undefined) container.inset = c.inset;
+  const turned: PackInput = { container, items: input.items.map(transposeItem) };
+  if (input.obstacles) turned.obstacles = input.obstacles.map((o) => ({ ...o, region: transposeRegion(o.region) }));
+  if (input.gap !== undefined) turned.gap = input.gap;
+  return turned;
+}
+
+/** This function gives an output with the axes changed. */
+export function transposeOutput(output: PackOutput): PackOutput {
+  return {
+    placements: output.placements.map((p) => ({ ...p, x: p.y, y: p.x })),
+    overflow: [...output.overflow],
+    size: { w: output.size.h, h: output.size.w },
+    moved: output.moved.map((m) => ({ id: m.id, x: m.y, y: m.x })),
+    trace: output.trace,
+  };
+}
+
+/**
+ * This function packs an input with a fixed height through the turn of the axes. It changes x for y in the input.
+ * Then it packs with a fixed width, and changes the axes of the output back.
+ */
+export function viaAxes(input: PackInput, previous: PackOutput | undefined, run: (turned: PackInput, previous: PackOutput | undefined) => PackOutput): PackOutput {
+  const start = now();
+  const turned = transposeInput(input);
+  const inner = run(turned, previous === undefined ? undefined : transposeOutput(previous));
+  const output = transposeOutput(inner);
+  output.trace = [{ id: "axes", ms: now() - start, measures: {} }, ...inner.trace];
+  return output;
+}

package/src/index.ts

@@ -7,3 +7,44 @@ export { packFree, aspectError, type FreeWidthOptions, type FreeWidthResult, typ
 export { compareRects, SORT_ORDERS, type SortOrder } from "./order.ts";
 export { pushCascade, type PushOptions } from "./push.ts";
 export { packingMetrics, type MetricsOptions, type PackingMetrics } from "./metrics.ts";
+export {
+  DEFAULT_TOLERANCE,
+  EPS,
+  RECORD_EPS,
+  marginOf,
+  turnItem,
+  turnPoint,
+  turnPort,
+  turnRegion,
+  type Container,
+  type Item,
+  type Margin,
+  type Obstacle,
+  type PackInput,
+  type PackOutput,
+  type Placement,
+  type Port,
+  type Region,
+  type StageTrace,
+  type Tolerance,
+} from "./contract.ts";
+export {
+  UnsupportedCell,
+  assertSupported,
+  cellOf,
+  createContext,
+  mulberry32,
+  supportsCell,
+  unsupportedOf,
+  type Cell,
+  type Dimension,
+  type DimensionValue,
+  type PackContext,
+  type SizeSearch,
+  type Strategy,
+  type Supports,
+} from "./strategy.ts";
+export { logSweep, push, rows, shelf, skyline, type LayoutStrategyOptions, type PushStrategyOptions } from "./adapters.ts";
+export { fromRects, toRects } from "./convert.ts";
+export { packWith, strategies, strategy } from "./registry.ts";
+export { checkHard, type HardBreaks } from "./check.ts";

package/src/pack.ts

@@ -70,7 +70,8 @@ function packRow<T>(rects: Rect<T>[], outer: Rect<T>, order: SortOrder): boolean
     if (fillGaps && row.length > 1) {
       const rectInRow = row[row.length - 1]!;
       const outerLeft = new Rect<T>();
-      outerLeft.position.set(rectInRow.position.x, rectInRow.bottom());
+      // The position of the region is relative to the outer rectangle, as packInto adds the position of the outer rectangle
+      outerLeft.position.set(rectInRow.position.x - outer.position.x, rectInRow.bottom() - outer.position.y);
       outerLeft.size.set(rectInRow.size.x, rowRect.size.y - rectInRow.size.y);
       outerLeft.fixedWidth = true;
       outerLeft.fixedSize = true;

package/src/registry.ts

@@ -0,0 +1,23 @@
+import { push, rows, shelf, skyline } from "./adapters.ts";
+import type { PackInput, PackOutput } from "./contract.ts";
+import { createContext, type Strategy } from "./strategy.ts";
+
+/** Each strategy of the package. The benchmark starts each one on each input of the corpus. */
+export const strategies: readonly Strategy[] = Object.freeze([rows, skyline, shelf, push] as Strategy[]);
+
+/** This function gives the strategy with an id. It throws a `RangeError` for an id that the registry does not have. */
+export function strategy(id: string): Strategy {
+  const found = strategies.find((s) => s.id === id);
+  if (found === undefined) throw new RangeError(`The registry has no strategy "${id}".`);
+  return found;
+}
+
+/**
+ * This function packs an input with the strategy of an id. The options go over the defaults of the strategy. The
+ * context gets `mulberry32` with the seed. The default seed is 0.
+ */
+export function packWith(id: string, input: PackInput, options?: unknown, seed = 0): PackOutput {
+  const s = strategy(id);
+  const merged: unknown = { ...(s.defaults as object), ...(options as object | undefined) };
+  return s.pack(input, merged, createContext(seed));
+}

package/src/strategy.ts

@@ -0,0 +1,214 @@
+import type { Container, PackInput, PackOutput, Region } from "./contract.ts";
+
+/** For each dimension of the taxonomy, the values that a strategy supports. `docs/research/TAXONOMY.md` gives the values. */
+export interface Supports {
+  containerSize: ("fixed" | "freeHeight" | "freeWidth" | "freeAspect" | "freeArea")[];
+  containerShape: ("rect" | "convex" | "polygon" | "circle" | "ellipse" | "holes")[];
+  /** The movement of the obstacles. An empty list supports only an input with no obstacle and no locked item. */
+  obstacleMove: ("fixed" | "costly" | "free")[];
+  itemShape: ("rect" | "circle" | "convex" | "polygon" | "mixed")[];
+  rotation: ("none" | "quarter" | "any")[];
+  order: ("free" | "soft" | "hard")[];
+  groups: ("none" | "flat" | "nested")[];
+  mode: ("offline" | "online" | "incremental")[];
+}
+
+/** A dimension of `Supports`. */
+export type Dimension = keyof Supports;
+
+/** A value of a dimension of `Supports`. */
+export type DimensionValue<D extends Dimension = Dimension> = Supports[D][number];
+
+/**
+ * The cell of an input: one value for each packer dimension that the input tells. The input does not tell the mode.
+ * Without obstacles and locked items, the cell has no `obstacleMove`.
+ */
+export interface Cell {
+  containerSize: DimensionValue<"containerSize">;
+  containerShape: DimensionValue<"containerShape">;
+  obstacleMove?: DimensionValue<"obstacleMove">;
+  itemShape: DimensionValue<"itemShape">;
+  rotation: DimensionValue<"rotation">;
+  order: DimensionValue<"order">;
+  groups: DimensionValue<"groups">;
+}
+
+/** The context of one packing. */
+export interface PackContext {
+  /** The seed. A strategy gets each random number from `rng`, not from `Math.random`. */
+  seed: number;
+  /** The random numbers in `[0, 1)`, from `mulberry32` with `seed`. */
+  rng: () => number;
+  /** A limit for the strategies that search. The strategy gives its best result at the limit. */
+  budget?: { ms?: number; steps?: number };
+  /** The previous output, for the mode `incremental`. */
+  previous?: PackOutput;
+}
+
+/** A packing strategy behind the Packer interface. */
+export interface Strategy<O = unknown> {
+  /** A stable name, for example `shelf`. The records use it. */
+  id: string;
+  /** The family of the catalog, for example `shelf` or `skyline`. */
+  family: string;
+  /** The ids of the catalog rows that this strategy builds. */
+  catalog: string[];
+  /** The cells that the strategy supports. */
+  supports: Supports;
+  /** The default options. A record writes the options in full. */
+  defaults: O;
+  /** The value `true` tells that the result depends only on the input, the options and the seed. */
+  deterministic: boolean;
+  /** This method packs an input. It throws `UnsupportedCell` for an input outside the cells of `supports`. */
+  pack(input: PackInput, options: O, context: PackContext): PackOutput;
+}
+
+/** A size search: it gives a strategy of a fixed width the cells `freeAspect` and `freeArea`. */
+export interface SizeSearch {
+  id: string;
+  /** This method searches the size of the container for an input with `fixed` set to `none`. `options` go to `inner`. */
+  search(input: PackInput, inner: Strategy, context: PackContext, options?: unknown): PackOutput;
+}
+
+/**
+ * The error of a strategy for an input outside its cells. The benchmark records this result. It is not a failure of the
+ * strategy.
+ */
+export class UnsupportedCell extends Error {
+  /** The dimension of the taxonomy. */
+  readonly dimension: Dimension;
+  /** The value of the input that the strategy does not support. */
+  readonly value: string;
+
+  constructor(dimension: Dimension, value: string) {
+    super(`The strategy does not support the value "${value}" of the dimension "${dimension}".`);
+    this.name = "UnsupportedCell";
+    this.dimension = dimension;
+    this.value = value;
+  }
+}
+
+/** This function gives a generator of random numbers in `[0, 1)`: `mulberry32` of `docs/FORMAT.md`. */
+export function mulberry32(seed: number): () => number {
+  let s = seed >>> 0;
+  return () => {
+    s = (s + 0x6d2b79f5) | 0;
+    let t = Math.imul(s ^ (s >>> 15), 1 | s);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** This function makes the context of one packing from a seed. */
+export function createContext(seed = 0, more: Omit<PackContext, "seed" | "rng"> = {}): PackContext {
+  return { ...more, seed, rng: mulberry32(seed) };
+}
+
+/** This function tells if a polygon ring is convex. A ring with fewer than 3 points is convex. */
+function isConvex(points: readonly [number, number][]): boolean {
+  let sign = 0;
+  const n = points.length;
+  for (let i = 0; i < n; i++) {
+    const [ax, ay] = points[i]!;
+    const [bx, by] = points[(i + 1) % n]!;
+    const [cx, cy] = points[(i + 2) % n]!;
+    const cross = (bx - ax) * (cy - by) - (by - ay) * (cx - bx);
+    if (cross === 0) continue;
+    if (sign === 0) sign = Math.sign(cross);
+    else if (Math.sign(cross) !== sign) return false;
+  }
+  return true;
+}
+
+/** This function gives the value of `containerShape` of one region. */
+function shapeOf(region: Region): DimensionValue<"containerShape"> {
+  switch (region.kind) {
+    case "rect":
+    case "circle":
+    case "ellipse":
+      return region.kind;
+    case "polygon":
+      if (region.holes && region.holes.length > 0) return "holes";
+      return isConvex(region.points) ? "convex" : "polygon";
+  }
+}
+
+/** This function gives the value of `itemShape` of one item shape. An ellipse is convex. */
+function itemShapeOf(region: Region | undefined): DimensionValue<"itemShape"> {
+  if (region === undefined) return "rect";
+  switch (region.kind) {
+    case "rect":
+    case "circle":
+      return region.kind;
+    case "ellipse":
+      return "convex";
+    case "polygon":
+      return !region.holes?.length && isConvex(region.points) ? "convex" : "polygon";
+  }
+}
+
+/**
+ * This function gives the cell of an input: the values of the packer dimensions that the input tells.
+ *
+ * - `containerSize` comes from `fixed`. The value `none` gives `freeArea` when `aspectWeight` is 0, and `freeAspect` if not.
+ * - `containerShape` comes from the shape. A rectangle container with an obstacle of another region gives `holes`.
+ * - `obstacleMove` is the hardest value of the obstacles and the locked items: `costly`, then `free`, then `fixed`.
+ * - `order` is `soft` when an item has a rank, and `free` if not. The input does not tell a hard order.
+ * - `groups` is `nested` when an item has a parent, `flat` when an item has a group, and `none` if not.
+ */
+export function cellOf(input: PackInput): Cell {
+  const { container, items } = input;
+  const obstacles = input.obstacles ?? [];
+
+  const sizes: Record<Container["fixed"], DimensionValue<"containerSize">> = {
+    size: "fixed",
+    width: "freeHeight",
+    height: "freeWidth",
+    none: container.aspectWeight === 0 ? "freeArea" : "freeAspect",
+  };
+  const containerSize = sizes[container.fixed];
+
+  let containerShape = container.shape ? shapeOf(container.shape) : "rect";
+  if (containerShape === "rect" && obstacles.some((o) => o.region.kind !== "rect")) containerShape = "holes";
+
+  let obstacleMove: DimensionValue<"obstacleMove"> | undefined = items.some((i) => i.locked === true) ? "fixed" : undefined;
+  for (const o of obstacles) {
+    const move = o.move === undefined ? "fixed" : o.move.cost > 0 ? "costly" : "free";
+    if (move === "costly" || obstacleMove === undefined || (move === "free" && obstacleMove === "fixed")) obstacleMove = move;
+  }
+
+  const shapes = new Set(items.map((i) => itemShapeOf(i.shape)));
+  const itemShape = shapes.size > 1 ? "mixed" : ([...shapes][0] ?? "rect");
+
+  const cell: Cell = {
+    containerSize,
+    containerShape,
+    itemShape,
+    rotation: items.some((i) => i.turnable === true) ? "quarter" : "none",
+    order: items.some((i) => i.rank !== undefined) ? "soft" : "free",
+    groups: items.some((i) => i.parent !== undefined) ? "nested" : items.some((i) => i.group !== undefined) ? "flat" : "none",
+  };
+  if (obstacleMove !== undefined) cell.obstacleMove = obstacleMove;
+  return cell;
+}
+
+/** This function gives the first dimension of a cell that `supports` does not hold, or `undefined` when it holds each one. */
+export function unsupportedOf(supports: Supports, cell: Partial<Record<Dimension, string>>): { dimension: Dimension; value: string } | undefined {
+  for (const dimension of Object.keys(supports) as Dimension[]) {
+    const value = cell[dimension];
+    if (value === undefined) continue;
+    if (!(supports[dimension] as readonly string[]).includes(value)) return { dimension, value };
+  }
+  return undefined;
+}
+
+/** This function tells if `supports` holds each value of a cell. A dimension that the cell does not have is held. */
+export function supportsCell(supports: Supports, cell: Partial<Record<Dimension, string>>): boolean {
+  return unsupportedOf(supports, cell) === undefined;
+}
+
+/** This function throws `UnsupportedCell` for the first value of the cell of an input that `supports` does not hold. */
+export function assertSupported(supports: Supports, input: PackInput): void {
+  const miss = unsupportedOf(supports, cellOf(input));
+  if (miss) throw new UnsupportedCell(miss.dimension, miss.value);
+}