tsdraft 0.3.0 → 0.4.0

package/dist/drawing.js

@@ -1,16 +1,53 @@
+import { holdCall, readCall, recordCalls } from "./callsite.js";
 import { fmt, written } from "./format.js";
 import { layerAuditKey, layerKey } from "./layers.js";
 import { BUILT_IN_LINETYPES, builtInLinetype } from "./linetypes.js";
-import { arcProblem, layerColorProblem, layerFlagProblem, layerLinetypeProblem, layerStateProblem, lineweightProblem, linetypeNameProblem, linetypeProblem, linetypeScaleProblem, magnitudeProblem, layerNameProblem, layerTwinProblem, R12_ONLY, sizeProblem, textProblem, undefinedLinetypeProblem, } from "./rules.js";
+import { DrawingError } from "./lint.js";
+import { arcProblem, duplicateIdProblem, idKey, idProblem, layerColorProblem, layerFlagProblem, layerLinetypeProblem, layerStateProblem, lineweightProblem, linetypeNameProblem, linetypeProblem, linetypeScaleProblem, magnitudeProblem, layerNameProblem, layerTwinProblem, R12_ONLY, sizeProblem, textProblem, undefinedLinetypeProblem, } from "./rules.js";
 const UNITS = ["in", "ft", "mm", "cm", "m"];
 const DXF_VERSIONS = ["R12", "R2018"];
+/** A broken rule, thrown inside a builder method and turned into a `DrawingError` on its way out. */
+class Problem {
+    rule;
+    message;
+    constructor(rule, message) {
+        this.rule = rule;
+        this.message = message;
+    }
+}
+function refuse(rule, message) {
+    throw new Problem(rule, message);
+}
+/**
+ * What a builder method throws for something thrown inside it: for a `Problem`, a `DrawingError`
+ * whose one diagnostic names the caller's call of `method` and what the call was `about`.
+ */
+function located(thrown, method, about) {
+    if (!(thrown instanceof Problem))
+        return thrown;
+    const call = readCall(holdCall(method));
+    const diagnostic = {
+        rule: thrown.rule,
+        severity: "error",
+        message: thrown.message,
+        ...about,
+        ...(call ? { call } : {}),
+    };
+    return new DrawingError([diagnostic], thrown.message);
+}
+/** Whether a tool that runs drawing files has asked every builder to record calls. */
+function recordsCalls() {
+    return globalThis.TSDRAFT_RECORD_CALLS === true;
+}
 /**
  * Builds a drawing. Entities go on the current layer, which starts as "0".
  * `layer(name, opts, draw)` scopes everything drawn inside `draw` to that layer.
  *
  * Mistakes written as literals, such as a layer name the DXF version does not
  * allow or a negative radius, are compile errors. The same checks run again
- * when the code runs, for values the compiler cannot see.
+ * when the code runs, for values the compiler cannot see: `layer`, `linetype`
+ * and the entity methods then throw a `DrawingError` whose diagnostic has the
+ * rule, the entity's `id` and the `call` that broke it.
  */
 export class DrawingBuilder {
     units;
@@ -25,6 +62,10 @@ export class DrawingBuilder {
     /** Seeded with the built-in linetypes, whose twins AUDIT reports as it reports any other. */
     #linetypesAudited = new Map(BUILT_IN_LINETYPES.map((name) => [layerAuditKey(name), name]));
     #entities = [];
+    /** The first spelling of each entity id, by `idKey`. */
+    #ids = new Map();
+    /** The call that drew each entity, when calls are recorded. */
+    #calls;
     #current = "0";
     constructor(options = {}) {
         const units = options.units ?? "in";
@@ -47,6 +88,7 @@ export class DrawingBuilder {
         this.units = units;
         this.dxf = dxf;
         this.linetypeScale = scale ?? 1;
+        this.#calls = (options.recordCalls ?? recordsCalls()) ? [] : undefined;
     }
     /**
      * Defines a linetype, or updates the one of the same name. `dashed` and
@@ -54,9 +96,17 @@ export class DrawingBuilder {
      * tsdraft exports the linetypes plans use, such as `DASHED` and `HIDDEN`.
      */
     linetype(linetype) {
-        if (this.dxf === "R12")
-            throw new Error(R12_ONLY.linetypes);
-        this.#define(linetype);
+        const definition = linetype;
+        try {
+            if (this.dxf === "R12")
+                refuse("linetype", R12_ONLY.linetypes);
+            this.#define(definition);
+        }
+        catch (thrown) {
+            const name = definition?.name;
+            const about = typeof name === "string" ? { linetype: name } : {};
+            throw located(thrown, DrawingBuilder.prototype.linetype, about);
+        }
         return this;
     }
     /**
@@ -67,23 +117,41 @@ export class DrawingBuilder {
     layer(name, options = {}, draw) {
         // The parameter type is the error message when a literal name is wrong, so read it as a string.
         const requested = name;
-        const fail = (problem) => {
-            throw new Error(`Layer ${JSON.stringify(requested)}: ${problem}`);
-        };
+        let layer;
+        try {
+            layer = this.#layer(requested, options);
+        }
+        catch (thrown) {
+            throw located(thrown, DrawingBuilder.prototype.layer, { layer: requested });
+        }
+        if (draw) {
+            const previous = this.#current;
+            this.#current = layer.name;
+            try {
+                draw();
+            }
+            finally {
+                this.#current = previous;
+            }
+        }
+        return this;
+    }
+    /** Checks a layer and stores it. */
+    #layer(requested, o) {
+        const fail = (rule, problem) => refuse(rule, `Layer ${JSON.stringify(requested)}: ${problem}`);
         const nameProblem = layerNameProblem(requested, this.dxf);
         if (nameProblem)
-            fail(nameProblem);
+            fail("layer-name", nameProblem);
         const key = layerKey(requested);
         const existing = this.#layers.get(key);
         const auditKey = layerAuditKey(requested);
         const twinProblem = layerTwinProblem(requested, this.#audited.get(auditKey) ?? requested);
         if (twinProblem)
-            fail(twinProblem);
-        const color = options.color ?? existing?.color ?? 7;
+            fail("duplicate-layer", twinProblem);
+        const color = o.color ?? existing?.color ?? 7;
         const colorProblem = layerColorProblem(color);
         if (colorProblem)
-            fail(colorProblem);
-        const o = options;
+            fail("layer-color", colorProblem);
         const layer = { name: existing?.name ?? requested, color };
         const set = (field, value, plain) => {
             const kept = value === undefined ? existing?.[field] : value;
@@ -94,80 +162,81 @@ export class DrawingBuilder {
         let linetype;
         if (o.linetype !== undefined) {
             if (r12 && !isBuiltIn(o.linetype, "Continuous"))
-                fail(R12_ONLY.linetypes);
+                fail("linetype", R12_ONLY.linetypes);
             linetype = this.#linetypeName(o.linetype, fail);
             const problem = layerLinetypeProblem(linetype);
             if (problem)
-                fail(problem);
+                fail("linetype", problem);
         }
         set("linetype", linetype === undefined ? undefined : (builtInLinetype(linetype) ?? linetype), "Continuous");
         if (o.lineweight !== undefined) {
             const problem = lineweightProblem(o.lineweight, "layer");
             if (problem)
-                fail(problem);
+                fail("lineweight", problem);
             if (r12 && o.lineweight !== "Default")
-                fail(R12_ONLY.lineweights);
+                fail("lineweight", R12_ONLY.lineweights);
         }
         set("lineweight", o.lineweight, "Default");
         for (const state of ["off", "frozen", "locked", "plot"]) {
             const value = o[state];
             const flagProblem = layerFlagProblem(state, value);
             if (flagProblem)
-                fail(flagProblem);
-            if (r12 && value !== undefined && value !== (state === "plot"))
-                fail(R12_ONLY.layerStates);
+                fail("layer-state", flagProblem);
+            if (r12 && value !== undefined && value !== (state === "plot")) {
+                fail("layer-state", R12_ONLY.layerStates);
+            }
             set(state, value, state === "plot");
         }
         const stateProblem = layerStateProblem(layer.name, layer.frozen);
         if (stateProblem)
-            fail(stateProblem);
+            fail("layer-state", stateProblem);
         this.#layers.set(key, layer);
         if (!this.#audited.has(auditKey))
             this.#audited.set(auditKey, layer.name);
-        if (draw) {
-            const previous = this.#current;
-            this.#current = layer.name;
-            try {
-                draw();
-            }
-            finally {
-                this.#current = previous;
-            }
-        }
-        return this;
+        return layer;
     }
     line(from, to, options = {}) {
-        return this.#add({ kind: "line", layer: this.#current, from: pt(from), to: pt(to) }, options);
+        return this.#add(DrawingBuilder.prototype.line, options, () => ({
+            kind: "line",
+            layer: this.#current,
+            from: pt(from),
+            to: pt(to),
+        }));
     }
     polyline(points, closed = false, options = {}) {
-        if (points.length < 2)
-            throw new Error("A polyline needs at least 2 points");
-        return this.#add({ kind: "polyline", layer: this.#current, points: points.map(pt), closed }, options);
+        return this.#add(DrawingBuilder.prototype.polyline, options, () => {
+            if (points.length < 2)
+                refuse("geometry", "A polyline needs at least 2 points");
+            return { kind: "polyline", layer: this.#current, points: points.map(pt), closed };
+        });
     }
     /** Closed rectangle from its lower-left corner. */
     rect(corner, width, height, options = {}) {
-        const [x, y] = pt(corner);
-        const w = positive(width, "width");
-        const h = positive(height, "height");
-        // A side can still vanish in the file: a corner and the one across from it may round together.
-        if (written(x + w) === written(x))
-            throw new Error(lostSide("width", "x", x));
-        if (written(y + h) === written(y))
-            throw new Error(lostSide("height", "y", y));
-        return this.polyline([
-            [x, y],
-            [x + w, y],
-            [x + w, y + h],
-            [x, y + h],
-        ], true, options);
+        return this.#add(DrawingBuilder.prototype.rect, options, () => {
+            const [x, y] = pt(corner);
+            const w = positive(width, "width");
+            const h = positive(height, "height");
+            // A side can still vanish in the file: a corner and the one across from it may round together.
+            if (written(x + w) === written(x))
+                refuse("geometry", lostSide("width", "x", x));
+            if (written(y + h) === written(y))
+                refuse("geometry", lostSide("height", "y", y));
+            const corners = [
+                [x, y],
+                [x + w, y],
+                [x + w, y + h],
+                [x, y + h],
+            ];
+            return { kind: "polyline", layer: this.#current, points: corners.map(pt), closed: true };
+        });
     }
     circle(center, radius, options = {}) {
-        return this.#add({
+        return this.#add(DrawingBuilder.prototype.circle, options, () => ({
             kind: "circle",
             layer: this.#current,
             center: pt(center),
             radius: positive(radius, "radius"),
-        }, options);
+        }));
     }
     /**
      * Arc from `startAngle` counterclockwise to `endAngle`. Angles are stored
@@ -179,61 +248,93 @@ export class DrawingBuilder {
      * arc of no length, so it throws: draw a circle instead.
      */
     arc(center, radius, startAngle, endAngle, options = {}) {
-        const start = turn(num(startAngle, "startAngle"));
-        const end = turn(num(endAngle, "endAngle"));
-        if (start === end)
-            throw new Error("An arc's start and end angles must differ");
-        const problem = arcProblem(start, end);
-        if (problem)
-            throw new Error(problem);
-        return this.#add({
-            kind: "arc",
-            layer: this.#current,
-            center: pt(center),
-            radius: positive(radius, "radius"),
-            startAngle: start,
-            endAngle: end,
-        }, options);
+        return this.#add(DrawingBuilder.prototype.arc, options, () => {
+            const start = turn(num(startAngle, "startAngle"));
+            const end = turn(num(endAngle, "endAngle"));
+            if (start === end)
+                refuse("geometry", "An arc's start and end angles must differ");
+            const problem = arcProblem(start, end);
+            if (problem)
+                refuse("geometry", problem);
+            return {
+                kind: "arc",
+                layer: this.#current,
+                center: pt(center),
+                radius: positive(radius, "radius"),
+                startAngle: start,
+                endAngle: end,
+            };
+        });
     }
     text(at, value, options = {}) {
-        const problem = textProblem(value);
-        if (problem)
-            throw new Error(problem);
-        return this.#add({
-            kind: "text",
-            layer: this.#current,
-            at: pt(at),
-            value,
-            height: positive(options.height ?? 0.125, "height"),
-            rotation: kept(options.rotation ?? 0, "rotation"),
-        }, options);
+        return this.#add(DrawingBuilder.prototype.text, options, () => {
+            const problem = textProblem(value);
+            if (problem)
+                refuse("text", problem);
+            return {
+                kind: "text",
+                layer: this.#current,
+                at: pt(at),
+                value,
+                height: positive(options.height ?? 0.125, "height"),
+                rotation: kept(options.rotation ?? 0, "rotation"),
+            };
+        });
     }
     build() {
+        const entities = [...this.#entities];
+        if (this.#calls)
+            recordCalls(entities, [...this.#calls]);
         return {
+            format: 0,
             units: this.units,
             dxf: this.dxf,
             layers: [...this.#layers.values()],
-            entities: [...this.#entities],
+            entities,
             linetypes: [...this.#linetypes.values()],
             linetypeScale: this.linetypeScale,
         };
     }
-    /** `options` is an `EntityOptions`, whose type parameters differ from method to method. */
-    #add(entity, options) {
-        this.#entities.push({ ...entity, ...this.#style(options) });
+    /**
+     * Checks the entity that `make` gives and the `EntityOptions` it was drawn with, whose type
+     * parameters differ from method to method, and stores it. `method` is the builder method the
+     * caller called, which a diagnostic names the call of.
+     */
+    #add(method, options, make) {
+        const o = options;
+        const id = o.id;
+        try {
+            const key = id === undefined ? undefined : this.#idKey(id);
+            const named = id === undefined ? {} : { id: id };
+            this.#entities.push({ ...make(), ...named, ...this.#style(o) });
+            if (key !== undefined)
+                this.#ids.set(key, id);
+        }
+        catch (thrown) {
+            throw located(thrown, method, typeof id === "string" ? { id } : {});
+        }
+        this.#calls?.push(holdCall(method));
         return this;
     }
+    /** Checks an id the drawing does not have yet, and returns the key it is kept by. */
+    #idKey(id) {
+        const problem = idProblem(id);
+        if (problem)
+            refuse("id", problem);
+        const key = idKey(id);
+        const first = this.#ids.get(key);
+        if (first !== undefined)
+            refuse("duplicate-id", duplicateIdProblem(id, first));
+        return key;
+    }
     /** The linetype and lineweight an entity is stored with. */
     #style(options) {
-        const fail = (problem) => {
-            throw new Error(problem);
-        };
         const style = {};
         if (options.linetype !== undefined) {
             if (this.dxf === "R12" && !isBuiltIn(options.linetype, "ByLayer")) {
-                fail(R12_ONLY.entityStyle);
+                refuse("linetype", R12_ONLY.entityStyle);
             }
-            const name = this.#linetypeName(options.linetype, fail);
+            const name = this.#linetypeName(options.linetype, refuse);
             const builtIn = builtInLinetype(name);
             if (builtIn !== "ByLayer")
                 style.linetype = builtIn ?? name;
@@ -242,9 +343,9 @@ export class DrawingBuilder {
         if (weight !== undefined) {
             const problem = lineweightProblem(weight, "entity");
             if (problem)
-                fail(problem);
+                refuse("lineweight", problem);
             if (this.dxf === "R12" && weight !== "ByLayer")
-                fail(R12_ONLY.entityStyle);
+                refuse("lineweight", R12_ONLY.entityStyle);
             if (weight !== "ByLayer")
                 style.lineweight = weight;
         }
@@ -258,14 +359,17 @@ export class DrawingBuilder {
         if (typeof choice === "object" && choice !== null) {
             return this.#define(choice, true);
         }
-        if (typeof choice !== "string")
-            return fail("A linetype is a name or a LinetypeDefinition");
+        if (typeof choice !== "string") {
+            return fail("undefined-linetype", "A linetype is a name or a LinetypeDefinition");
+        }
         const problem = linetypeNameProblem(choice);
         if (problem)
-            fail(`Linetype ${JSON.stringify(choice)}: ${problem}`);
+            fail("undefined-linetype", `Linetype ${JSON.stringify(choice)}: ${problem}`);
         const known = builtInLinetype(choice) ?? this.#linetypes.get(layerKey(choice))?.name;
-        if (known === undefined)
-            fail(`${undefinedLinetypeProblem(choice)}. Define it with linetype() first`);
+        if (known === undefined) {
+            const absent = `${undefinedLinetypeProblem(choice)}. Define it with linetype() first`;
+            fail("undefined-linetype", absent);
+        }
         return known;
     }
     /**
@@ -277,7 +381,7 @@ export class DrawingBuilder {
         const label = `Linetype ${JSON.stringify(definition.name)}`;
         const problem = linetypeProblem(definition.name, definition.description ?? "", definition.pattern);
         if (problem)
-            throw new Error(`${label}: ${problem}`);
+            refuse("linetype", `${label}: ${problem}`);
         // linetypeProblem has checked the types.
         const name = definition.name;
         const description = (definition.description ?? "");
@@ -286,14 +390,14 @@ export class DrawingBuilder {
         const auditKey = layerAuditKey(name);
         const twin = layerTwinProblem(name, this.#linetypesAudited.get(auditKey) ?? name, "linetype");
         if (twin)
-            throw new Error(`${label}: ${twin}`);
+            refuse("duplicate-linetype", `${label}: ${twin}`);
         const existing = this.#linetypes.get(key);
         if (inline && existing) {
             const same = existing.description === description &&
                 existing.pattern.length === lengths.length &&
                 existing.pattern.every((length, i) => length === lengths[i]);
             if (!same) {
-                throw new Error(`${label}: the drawing has a linetype of this name with another pattern or description. Pass its name, or change it with linetype()`);
+                refuse("linetype", `${label}: the drawing has a linetype of this name with another pattern or description. Pass its name, or change it with linetype()`);
             }
             return existing.name;
         }
@@ -327,17 +431,17 @@ function turn(degrees) {
 }
 function num(value, label) {
     if (!Number.isFinite(value))
-        throw new Error(`${label} must be a finite number`);
+        refuse("geometry", `${label} must be a finite number`);
     return value;
 }
 /** Takes `unknown` because a `Positive<N>` parameter is a message string when the literal is wrong. */
 function positive(value, label) {
     if (typeof value !== "number" || !Number.isFinite(value)) {
-        throw new Error(`${label} must be a finite number`);
+        return refuse("geometry", `${label} must be a finite number`);
     }
     const problem = sizeProblem(value);
     if (problem)
-        throw new Error(`${label}: ${problem}`);
+        refuse("geometry", `${label}: ${problem}`);
     return value;
 }
 function lostSide(size, axis, at) {
@@ -347,7 +451,7 @@ function lostSide(size, axis, at) {
 function kept(value, label) {
     const problem = magnitudeProblem(num(value, label));
     if (problem)
-        throw new Error(`${label}: ${problem}`);
+        refuse("geometry", `${label}: ${problem}`);
     return value;
 }
 function pt(point) {

package/dist/index.d.ts

@@ -1,6 +1,9 @@
+export type { CallSite } from "./callsite.ts";
 export { createDrawing, DrawingBuilder, sweep, type Arc, type Circle, type Drawing, type DrawingOptions, type DxfVersion, type Entity, type EntityOptions, type Layer, type LayerOptions, type Line, type Linetype, type LinetypeChoice, type LinetypeDefinition, type Lineweight, type Point, type Polyline, type Text, type TextOptions, type Units, } from "./drawing.ts";
 export { toDXF, type DxfOptions } from "./dxf.ts";
+export { fromJSON, toJSON } from "./json.ts";
 export { DrawingError, lint, type Diagnostic, type LintOptions, type LintRule } from "./lint.ts";
 export { CENTER, DASHDOT, DASHED, DOT, HIDDEN, LINEWEIGHTS, PHANTOM } from "./linetypes.ts";
-export type { Aci, Description, LayerColor, LayerLinetypeName, LayerName, LineweightOf, LinetypeName, NewLinetypeName, Pattern, Positive, } from "./rules.ts";
+export { fromPaper, type PaperScale, type PaperUnit } from "./paper.ts";
+export type { Aci, Description, EntityId, LayerColor, LayerLinetypeName, LayerName, LineweightOf, LinetypeName, NewLinetypeName, PaperLength, Pattern, Positive, Ratio, } from "./rules.ts";
 export { toSVG, type SvgOptions } from "./svg.ts";

package/dist/index.js

@@ -1,5 +1,7 @@
 export { createDrawing, DrawingBuilder, sweep, } from "./drawing.js";
 export { toDXF } from "./dxf.js";
+export { fromJSON, toJSON } from "./json.js";
 export { DrawingError, lint } from "./lint.js";
 export { CENTER, DASHDOT, DASHED, DOT, HIDDEN, LINEWEIGHTS, PHANTOM } from "./linetypes.js";
+export { fromPaper } from "./paper.js";
 export { toSVG } from "./svg.js";

package/dist/json.d.ts

@@ -0,0 +1,21 @@
+import type { Drawing } from "./drawing.ts";
+/**
+ * Writes the drawing as canonical JSON: no white space, the keys of every object in code-unit
+ * order, and each number in the shortest form that reads back as the same number, with `-0`
+ * for negative zero. Two drawings that are equal give the same string, whatever order their
+ * keys were set in. A field that is `undefined` is left out.
+ *
+ * The drawing is written as it is and is not checked: `fromJSON` checks it when it is read.
+ * Throws when the drawing holds a value JSON cannot, such as `NaN`.
+ */
+export declare function toJSON(drawing: Drawing): string;
+/**
+ * Reads a drawing from JSON, as a string or as the value `JSON.parse` gives, which is returned
+ * as the drawing when it passes.
+ *
+ * It refuses a format version it does not know, a field or an entity kind it does not know, a
+ * missing field and a value of the wrong type, and then every error `lint` finds, so a drawing
+ * that was read has passed each check the builder makes. It throws a `DrawingError` whose
+ * diagnostics name each problem, with the rule `"format"` for the ones `lint` does not look for.
+ */
+export declare function fromJSON(json: unknown): Drawing;