tsdraft 0.2.2 → 0.4.0

package/dist/callsite.js

@@ -0,0 +1,82 @@
+// Where in the caller's code a builder method was called. The location comes from the engine's
+// stack, so it holds a path of the machine the drawing was built on. It is kept beside the
+// drawing, never in it.
+/** The calls that drew a drawing's entities, by its `entities` array and each entity's index. */
+const recorded = new WeakMap();
+/**
+ * Captures the call of the builder method `method` that is running now, to be read later, or
+ * returns undefined where the engine gives no stack. It must be called from the builder's file.
+ *
+ * With `Error.captureStackTrace` the engine leaves out every frame down to `method`, so only the
+ * caller's frame is captured. Without it, the whole stack of a new error is kept.
+ */
+export function holdCall(method) {
+    const errors = Error;
+    try {
+        if (typeof errors.captureStackTrace !== "function") {
+            return { stack: new Error().stack, whole: true };
+        }
+        const held = { whole: false };
+        const limit = errors.stackTraceLimit;
+        const limited = typeof limit === "number";
+        if (limited)
+            errors.stackTraceLimit = 1;
+        try {
+            errors.captureStackTrace(held, method);
+        }
+        finally {
+            if (limited)
+                errors.stackTraceLimit = limit;
+        }
+        return held;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The location a held call names, or undefined when its stack has none. */
+export function readCall(held) {
+    if (!held)
+        return undefined;
+    try {
+        const stack = held.stack;
+        if (typeof stack !== "string")
+            return undefined;
+        return held.whole ? callerInStack(stack) : parseStack(stack)[0];
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The caller's frame in a whole stack captured by `holdCall`: the first frame in neither of
+ * tsdraft's two files on it, which are those of the first frame, `holdCall`'s own, and of the
+ * second, the builder's. Frames are told apart by file and not counted, because an engine may
+ * leave a frame out. When the caller's code is in one file with tsdraft, as in a bundle, no
+ * frame qualifies and there is no location, which is better than a line inside tsdraft.
+ */
+export function callerInStack(stack) {
+    const [capture, builder, ...rest] = parseStack(stack);
+    return rest.find((frame) => frame.file !== capture?.file && frame.file !== builder?.file);
+}
+/** Keeps the calls that drew `entities`, one for each entity in order. */
+export function recordCalls(entities, calls) {
+    recorded.set(entities, calls);
+}
+/** The call that drew the entity at `index` of `entities`, when the builder recorded it. */
+export function callOf(entities, index) {
+    return readCall(recorded.get(entities)?.[index]);
+}
+/**
+ * The location of each frame of a stack, innermost first. V8 writes a frame as
+ * `at name (file:1:2)` or `at file:1:2`, and Firefox and Safari as `name@file:1:2`. A line that
+ * is no frame, such as the error's message, is left out.
+ */
+export function parseStack(stack) {
+    return stack.split("\n").flatMap((line) => {
+        const frame = /^\s*at .*?\((.+):(\d+):(\d+)\)$/.exec(line) ??
+            /^\s*at (.+):(\d+):(\d+)$/.exec(line) ??
+            /^[^@]*@(.+):(\d+):(\d+)$/.exec(line);
+        return frame ? [{ file: frame[1], line: Number(frame[2]), column: Number(frame[3]) }] : [];
+    });
+}

package/dist/drawing.d.ts

@@ -1,4 +1,4 @@
-import { type LayerColor, type LayerName, type Positive } from "./rules.ts";
+import { type Description, type EntityId, type FrozenCurrent, type LayerLinetypeName, type LineweightMm, type LineweightOf, type LinetypeName, type NewLinetypeName, type Pattern, type R12EntityStyle, type R12LayerStates, type R12Lineweights, type R12Linetypes, type LayerColor, type LayerName, type Positive } from "./rules.ts";
 /** A model-space point, in drawing units. Y points up, as in CAD. */
 export type Point = readonly [x: number, y: number];
 /**
@@ -15,13 +15,53 @@ export type Units = "in" | "ft" | "mm" | "cm" | "m";
  *   used since 2018. It records the drawing's units.
  */
 export type DxfVersion = "R12" | "R2018";
+/**
+ * A simple linetype: a repeating pattern of dashes, gaps and dots. The lengths are in drawing
+ * units, and CAD multiplies them by the drawing's `linetypeScale`.
+ */
+export interface Linetype {
+    readonly name: string;
+    readonly description: string;
+    /** A dash is a positive length, a gap a negative one, and a dot 0. Empty for a solid line. */
+    readonly pattern: readonly number[];
+}
+/**
+ * The lineweights AutoCAD offers, in millimetres. A lineweight is how wide a line plots, and
+ * how wide AutoCAD shows it when LWDISPLAY is on.
+ */
+export type Lineweight = LineweightMm;
 export interface Layer {
     readonly name: string;
     /** AutoCAD Color Index, 1 to 255. 7 is white on dark backgrounds, black on light. */
     readonly color: number;
+    /** The linetype of the layer's entities that draw ByLayer. Defaults to `"Continuous"`. */
+    readonly linetype?: string;
+    /**
+     * In millimetres, one of `Lineweight`, or `"Default"`, which AutoCAD draws at its LWDEFAULT
+     * of 0.25 mm. Defaults to `"Default"`.
+     */
+    readonly lineweight?: number | "Default";
+    /** An off layer is not shown or plotted, but CAD still regenerates it. */
+    readonly off?: boolean;
+    /** A frozen layer is not shown, plotted or regenerated. */
+    readonly frozen?: boolean;
+    /** A locked layer is shown and plotted, and CAD does not let its entities be edited. */
+    readonly locked?: boolean;
+    /** Whether the layer plots. Defaults to `true`. */
+    readonly plot?: boolean;
 }
 interface EntityBase {
+    /**
+     * A name for this entity that stays the same when the drawing's code changes around it: 1 to
+     * 64 letters A to Z or a to z, digits, `.`, `-` and `_`. No two entities of a drawing share
+     * one, whatever its case.
+     */
+    readonly id?: string;
     readonly layer: string;
+    /** A linetype of the drawing, `"Continuous"`, `"ByBlock"` or `"ByLayer"`, the default. */
+    readonly linetype?: string;
+    /** In millimetres, one of `Lineweight`, or `"ByLayer"`, the default, `"ByBlock"` or `"Default"`. */
+    readonly lineweight?: number | "ByLayer" | "ByBlock" | "Default";
 }
 export interface Line extends EntityBase {
     readonly kind: "line";
@@ -57,23 +97,121 @@ export interface Text extends EntityBase {
 }
 export type Entity = Line | Polyline | Circle | Arc | Text;
 export interface Drawing {
+    /**
+     * The version of the `Drawing` format, which is separate from the DXF version in `dxf`.
+     * Format 0 carries no promise of stability: a later tsdraft may change it without reading it.
+     */
+    readonly format: 0;
     readonly units: Units;
     /** The DXF version the drawing is written for. `toDXF` uses it unless told otherwise. */
     readonly dxf: DxfVersion;
     readonly layers: readonly Layer[];
     readonly entities: readonly Entity[];
+    /** Linetypes beyond `Continuous`, `ByLayer` and `ByBlock`, which every drawing has. */
+    readonly linetypes?: readonly Linetype[];
+    /** The global linetype scale, `$LTSCALE`, which multiplies every pattern. Defaults to 1. */
+    readonly linetypeScale?: number;
 }
-export interface DrawingOptions<V extends DxfVersion = DxfVersion> {
+export interface DrawingOptions<V extends DxfVersion = DxfVersion, S extends number = number> {
     /** Defaults to `"in"`. */
     readonly units?: Units;
-    /** The DXF version to check the drawing against and export. Defaults to `"R12"`. */
+    /** The DXF version to check the drawing against and export. Defaults to `"R2018"`. */
     readonly dxf?: V;
+    /** The global linetype scale, which multiplies every linetype's pattern. Defaults to 1. */
+    readonly linetypeScale?: V extends "R12" ? 1 | R12Linetypes : Positive<S>;
+    /**
+     * Whether to record the call that draws each entity, so that a `lint` diagnostic names it in
+     * `call`. It more than doubles the time the builder takes. Defaults to `false`, or to `true` when
+     * `globalThis.TSDRAFT_RECORD_CALLS` is `true`, which a tool that runs drawing files sets
+     * before it runs them.
+     */
+    readonly recordCalls?: boolean;
+}
+/** A linetype to define: a `Linetype`, whose description may be left out. */
+export interface LinetypeDefinition<N extends string = string, P extends readonly number[] = readonly number[], D extends string = string> {
+    readonly name: NewLinetypeName<N>;
+    /** Shown beside the name in CAD's linetype lists. Defaults to `""`. */
+    readonly description?: Description<D>;
+    /** A dash is a positive length, a gap a negative one, and a dot 0. Empty for a solid line. */
+    readonly pattern: Pattern<P>;
 }
-export interface LayerOptions<C extends number = number> {
+/** What a layer or an entity may be given as its linetype: a name, or a definition. */
+type LinetypeValue = string | LinetypeDefinition;
+/** Each definition in `L`, checked as `linetype()` checks one. A name in `L` adds nothing. */
+type CheckedDefinition<L> = L extends LinetypeDefinition ? LinetypeDefinition<L["name"], L["pattern"], DescriptionOf<L>> : never;
+type DescriptionOf<L> = L extends {
+    readonly description: infer D extends string;
+} ? D : string;
+/**
+ * A linetype for a layer or an entity: the name `T` of one the drawing has, or a
+ * `LinetypeDefinition`, which is checked as `linetype()` checks one and defined first if the
+ * drawing does not have it yet.
+ *
+ * `L` is the whole value given, a name or a definition, so the compiler infers it in one piece
+ * even from a conditional that mixes the two. That is why this is one conditional type and not a
+ * union: the compiler infers a union's members apart. The false branch is never taken: it is
+ * there so the compiler infers `L`, and the tuple keeps `const L` from widening it.
+ */
+export type LinetypeChoice<T extends string, L extends LinetypeValue = LinetypeDefinition> = [
+    L
+] extends [LinetypeValue] ? LinetypeName<T> | CheckedDefinition<L> : L;
+/**
+ * A linetype on an R12 drawing, which can only be the built-in `Allowed`. Any other literal name,
+ * and any definition, resolves to `Message`. `L` holds a definition when it has an object in it
+ * and is not left at its default, `LinetypeDefinition`. The last branch, never taken, lets `L` be
+ * inferred, as in `LinetypeChoice`.
+ */
+type R12LinetypeChoice<T extends string, L extends LinetypeValue, Allowed extends string, Message> = [L] extends [LinetypeValue] ? LinetypeDefinition extends L ? R12LinetypeName<T, Allowed, Message> : [Extract<L, object>] extends [never] ? R12LinetypeName<T, Allowed, Message> : Message : L;
+type R12LinetypeName<T extends string, Allowed extends string, Message> = string extends T ? T : Lowercase<T> extends Allowed ? T : Message;
+/**
+ * What `layer()` sets on a layer.
+ *
+ * @typeParam L - The linetype as written, a name or a definition. A definition's literal mistakes
+ *   are compile errors.
+ */
+export interface LayerOptions<C extends number = number, W extends number = number, T extends string = string, V extends DxfVersion = "R2018", N extends string = string, L extends LinetypeValue = LinetypeDefinition> {
     /** AutoCAD Color Index, 1 to 255. */
     readonly color?: LayerColor<C>;
+    /** Defaults to `"Continuous"`. It cannot be ByLayer or ByBlock. R2018 only. */
+    readonly linetype?: V extends "R12" ? R12LinetypeChoice<T, L, "continuous", R12Linetypes> : [
+        L
+    ] extends [LinetypeValue] ? LayerLinetypeName<T> | CheckedDefinition<L> : L;
+    /** In millimetres, or `"Default"`, which is 0.25 mm. Defaults to `"Default"`. R2018 only. */
+    readonly lineweight?: V extends "R12" ? "Default" | R12Lineweights : LineweightOf<W> | "Default";
+    /** Hides the layer. R2018 only. */
+    readonly off?: V extends "R12" ? false | R12LayerStates : boolean;
+    /** Hides the layer and leaves it out of regeneration. Layer "0" cannot be frozen. R2018 only. */
+    readonly frozen?: V extends "R12" ? false | R12LayerStates : N extends "0" ? false | FrozenCurrent : boolean;
+    /** Keeps the layer's entities from being edited in CAD. R2018 only. */
+    readonly locked?: V extends "R12" ? false | R12LayerStates : boolean;
+    /** Whether the layer plots. Defaults to `true`. R2018 only. */
+    readonly plot?: V extends "R12" ? true | R12LayerStates : boolean;
 }
-export interface TextOptions<H extends number = number> {
+/**
+ * The id an entity may have, and the linetype and lineweight it may have of its own. Both
+ * default to ByLayer.
+ *
+ * @typeParam L - The linetype as written, a name or a definition. A definition's literal mistakes
+ *   are compile errors.
+ */
+export interface EntityOptions<V extends DxfVersion = "R2018", T extends string = string, W extends number = number, L extends LinetypeValue = LinetypeDefinition, I extends string = string> {
+    /**
+     * A name for the entity that no other entity of the drawing has: 1 to 64 letters A to Z or a
+     * to z, digits, `.`, `-` and `_`. Diagnostics and `toSVG` carry it.
+     */
+    readonly id?: EntityId<I>;
+    /** A linetype of the drawing, `"Continuous"`, `"ByBlock"` or `"ByLayer"`. R2018 only. */
+    readonly linetype?: V extends "R12" ? R12LinetypeChoice<T, L, "bylayer", R12EntityStyle> : LinetypeChoice<T, L>;
+    /** In millimetres, or `"ByLayer"`, `"ByBlock"` or `"Default"`. R2018 only. */
+    readonly lineweight?: V extends "R12" ? "ByLayer" | R12EntityStyle : LineweightOf<W> | "ByLayer" | "ByBlock" | "Default";
+}
+/**
+ * The options of `text()`: its height and rotation, and the options of every entity.
+ *
+ * @typeParam L - The linetype as written, a name or a definition. A definition's literal mistakes
+ *   are compile errors.
+ */
+export interface TextOptions<H extends number = number, V extends DxfVersion = "R2018", T extends string = string, W extends number = number, L extends LinetypeValue = LinetypeDefinition, I extends string = string> extends EntityOptions<V, T, W, L, I> {
     readonly height?: Positive<H>;
     /** Degrees counterclockwise. */
     readonly rotation?: number;
@@ -84,23 +222,33 @@ export interface TextOptions<H extends number = number> {
  *
  * 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 declare class DrawingBuilder<V extends DxfVersion = "R12"> {
+export declare class DrawingBuilder<V extends DxfVersion = "R2018", S extends number = number> {
     #private;
     readonly units: Units;
     readonly dxf: V;
-    constructor(options?: DrawingOptions<V>);
+    readonly linetypeScale: number;
+    constructor(options?: DrawingOptions<V, S>);
+    /**
+     * Defines a linetype, or updates the one of the same name. `dashed` and
+     * `DASHED` are the same linetype, as in CAD, and keep the first spelling.
+     * tsdraft exports the linetypes plans use, such as `DASHED` and `HIDDEN`.
+     */
+    linetype<N extends string, const P extends readonly number[], D extends string = string>(linetype: V extends "R12" ? R12Linetypes : LinetypeDefinition<N, P, D>): this;
     /**
      * Defines or updates a layer. With `draw`, entities drawn inside it go on this layer.
      * `wall` and `WALL` are the same layer, as in CAD, and keep the first spelling.
+     * Options left out keep the values the layer has.
      */
-    layer<N extends string, C extends number = number>(name: LayerName<N, V>, options?: LayerOptions<C>, draw?: () => void): this;
-    line(from: Point, to: Point): this;
-    polyline(points: readonly Point[], closed?: boolean): this;
+    layer<N extends string, C extends number = number, W extends number = number, T extends string = string, const L extends LinetypeValue = LinetypeDefinition>(name: LayerName<N, V>, options?: LayerOptions<C, W, T, V, N, L>, draw?: () => void): this;
+    line<T extends string = string, W extends number = number, const L extends LinetypeValue = LinetypeDefinition, I extends string = string>(from: Point, to: Point, options?: EntityOptions<V, T, W, L, I>): this;
+    polyline<T extends string = string, W extends number = number, const L extends LinetypeValue = LinetypeDefinition, I extends string = string>(points: readonly Point[], closed?: boolean, options?: EntityOptions<V, T, W, L, I>): this;
     /** Closed rectangle from its lower-left corner. */
-    rect<W extends number, H extends number>(corner: Point, width: Positive<W>, height: Positive<H>): this;
-    circle<R extends number>(center: Point, radius: Positive<R>): this;
+    rect<W extends number, H extends number, T extends string = string, LW extends number = number, const L extends LinetypeValue = LinetypeDefinition, I extends string = string>(corner: Point, width: Positive<W>, height: Positive<H>, options?: EntityOptions<V, T, LW, L, I>): this;
+    circle<R extends number, T extends string = string, W extends number = number, const L extends LinetypeValue = LinetypeDefinition, I extends string = string>(center: Point, radius: Positive<R>, options?: EntityOptions<V, T, W, L, I>): this;
     /**
      * Arc from `startAngle` counterclockwise to `endAngle`. Angles are stored
      * from 0 up to 360, so -90 becomes 270, because AutoCAD's AUDIT rejects
@@ -110,11 +258,11 @@ export declare class DrawingBuilder<V extends DxfVersion = "R12"> {
      * full turn would be written with equal angles, which AutoCAD holds as an
      * arc of no length, so it throws: draw a circle instead.
      */
-    arc<R extends number>(center: Point, radius: Positive<R>, startAngle: number, endAngle: number): this;
-    text<H extends number = number>(at: Point, value: string, options?: TextOptions<H>): this;
+    arc<R extends number, T extends string = string, W extends number = number, const L extends LinetypeValue = LinetypeDefinition, I extends string = string>(center: Point, radius: Positive<R>, startAngle: number, endAngle: number, options?: EntityOptions<V, T, W, L, I>): this;
+    text<H extends number = number, T extends string = string, W extends number = number, const L extends LinetypeValue = LinetypeDefinition, I extends string = string>(at: Point, value: string, options?: TextOptions<H, V, T, W, L, I>): this;
     build(): Drawing;
 }
-export declare function createDrawing<V extends DxfVersion = "R12">(options?: DrawingOptions<V>): DrawingBuilder<V>;
+export declare function createDrawing<V extends DxfVersion = "R2018", S extends number = number>(options?: DrawingOptions<V, S>): DrawingBuilder<V>;
 /** Counterclockwise sweep from start to end, in degrees, within [0, 360). */
 export declare function sweep(startAngle: number, endAngle: number): number;
 export {};