/**
* Geometric shapes demonstrating classes, interfaces, enums, function
* overloads, const assertions, and richer JSDoc tags.
* @module
*/
/** Supported shape categories. */
export enum ShapeKind {
Circle = 'circle',
Rectangle = 'rectangle',
}
/** Cardinal directions as a const enum (inlined at use sites). */
export const enum Direction {
North,
East,
South,
West,
}
/** Anything with a computable area. */
export interface HasArea {
/** Area in square units. */
readonly area: number;
}
/** Options for drawing a shape outline. */
export interface DrawOptions {
/**
* Stroke color as a CSS color string.
* @default 'black'
*/
stroke?: string;
/** Line width in pixels. */
width?: number;
}
/**
* An axis-aligned rectangle.
* @since 0.6.0
* @see `shape_area`
*/
export class Rectangle implements HasArea {
/** Shared kind tag for all rectangles. */
static readonly kind = ShapeKind.Rectangle;
/** Width in units. */
width: number;
/** Height in units. */
height: number;
// private state is excluded from extraction
#draw_count = 0;
/**
* @param width - initial width
* @param height - initial height
* @throws `RangeError` when either dimension is negative
*/
constructor(width: number, height: number) {
if (width < 0 || height < 0) throw new RangeError('dimensions must be non-negative');
this.width = width;
this.height = height;
}
/** Area in square units. */
get area(): number {
return this.width * this.height;
}
/** Longest side; setting it makes the rectangle a square. */
get size(): number {
return Math.max(this.width, this.height);
}
set size(value: number) {
this.width = value;
this.height = value;
}
/**
* Scale both dimensions in place.
* @param factor - multiplier applied to width and height
* @mutates `this`
*/
scale(factor: number): void {
this.width *= factor;
this.height *= factor;
}
/** Number of times this rectangle has been drawn, for subclasses. */
protected count_draw(): number {
return ++this.#draw_count;
}
}
/**
* Compute the area of a shape.
* @param shape - the shape to measure
* @returns the shape's area
* @example
* ```ts
* shape_area(new Rectangle(2, 3)) // 6
* shape_area(1) // Math.PI
* ```
*/
export function shape_area(shape: HasArea): number;
/**
* Compute the area of a circle from its radius.
* @param radius - circle radius in units
* @returns the circle's area
*/
export function shape_area(radius: number): number;
export function shape_area(shape_or_radius: HasArea | number): number {
return typeof shape_or_radius === 'number'
? Math.PI * shape_or_radius ** 2
: shape_or_radius.area;
}
/**
* Describe a shape for display.
* @param shape - the shape to describe
* @param options - formatting options
* @param options.precision - decimal places for the area
* @param options.label - prefix for the description
* @returns a human-readable description
*/
export const describe_shape = (
shape: HasArea,
options: {precision?: number; label?: string} = {},
): string => `${options.label ?? 'shape'}: area ${shape.area.toFixed(options.precision ?? 2)}`;
/** Unit square corners as a readonly tuple (const assertion). */
export const UNIT_SQUARE = [
{x: 0, y: 0},
{x: 1, y: 0},
{x: 1, y: 1},
{x: 0, y: 1},
] as const;
{
"path": "shapes.ts",
"declarations": [
{
"name": "shape_area",
"kind": "function",
"docComment": "Compute the area of a shape.",
"typeSignature": "(shape: HasArea): number",
"sourceLine": 106,
"examples": [
"```ts\nshape_area(new Rectangle(2, 3)) // 6\nshape_area(1) // Math.PI\n```"
],
"parameters": [
{
"name": "shape",
"type": "HasArea",
"description": "the shape to measure"
}
],
"overloads": [
{
"typeSignature": "(shape: HasArea): number",
"parameters": [
{
"name": "shape",
"type": "HasArea",
"description": "the shape to measure"
}
],
"returnType": "number",
"docComment": "Compute the area of a shape.",
"returnDescription": "the shape's area"
},
{
"typeSignature": "(radius: number): number",
"parameters": [
{
"name": "radius",
"type": "number",
"description": "circle radius in units"
}
],
"returnType": "number",
"docComment": "Compute the area of a circle from its radius.",
"returnDescription": "the circle's area"
}
],
"returnType": "number",
"returnDescription": "the shape's area"
},
{
"name": "ShapeKind",
"kind": "enum",
"docComment": "Supported shape categories.",
"typeSignature": "ShapeKind",
"sourceLine": 8,
"members": [
{
"name": "Circle",
"kind": "variable",
"typeSignature": "ShapeKind.Circle"
},
{
"name": "Rectangle",
"kind": "variable",
"typeSignature": "ShapeKind.Rectangle"
}
]
},
{
"name": "Direction",
"kind": "enum",
"docComment": "Cardinal directions as a const enum (inlined at use sites).",
"typeSignature": "Direction",
"sourceLine": 14,
"members": [
{
"name": "North",
"kind": "variable",
"typeSignature": "Direction.North"
},
{
"name": "East",
"kind": "variable",
"typeSignature": "Direction.East"
},
{
"name": "South",
"kind": "variable",
"typeSignature": "Direction.South"
},
{
"name": "West",
"kind": "variable",
"typeSignature": "Direction.West"
}
]
},
{
"name": "HasArea",
"kind": "interface",
"docComment": "Anything with a computable area.",
"typeSignature": "HasArea",
"sourceLine": 22,
"members": [
{
"name": "area",
"kind": "variable",
"docComment": "Area in square units.",
"typeSignature": "number",
"modifiers": [
"readonly"
]
}
]
},
{
"name": "DrawOptions",
"kind": "interface",
"docComment": "Options for drawing a shape outline.",
"typeSignature": "DrawOptions",
"sourceLine": 28,
"members": [
{
"name": "stroke",
"kind": "variable",
"docComment": "Stroke color as a CSS color string.",
"typeSignature": "string",
"optional": true,
"defaultValue": "'black'"
},
{
"name": "width",
"kind": "variable",
"docComment": "Line width in pixels.",
"typeSignature": "number",
"optional": true
}
]
},
{
"name": "Rectangle",
"kind": "class",
"docComment": "An axis-aligned rectangle.",
"sourceLine": 43,
"seeAlso": [
"`shape_area`"
],
"since": "0.6.0",
"implements": [
"HasArea"
],
"members": [
{
"name": "kind",
"kind": "variable",
"docComment": "Shared kind tag for all rectangles.",
"typeSignature": "ShapeKind.Rectangle",
"modifiers": [
"static",
"readonly"
]
},
{
"name": "width",
"kind": "variable",
"docComment": "Width in units.",
"typeSignature": "number"
},
{
"name": "height",
"kind": "variable",
"docComment": "Height in units.",
"typeSignature": "number"
},
{
"name": "constructor",
"kind": "constructor",
"typeSignature": "(width: number, height: number): Rectangle",
"throws": [
{
"description": "`RangeError` when either dimension is negative"
}
],
"parameters": [
{
"name": "width",
"type": "number",
"description": "initial width"
},
{
"name": "height",
"type": "number",
"description": "initial height"
}
]
},
{
"name": "scale",
"kind": "function",
"docComment": "Scale both dimensions in place.",
"typeSignature": "(factor: number): void",
"parameters": [
{
"name": "factor",
"type": "number",
"description": "multiplier applied to width and height"
}
],
"returnType": "void"
},
{
"name": "count_draw",
"kind": "function",
"docComment": "Number of times this rectangle has been drawn, for subclasses.",
"typeSignature": "(): number",
"modifiers": [
"protected"
],
"returnType": "number"
},
{
"name": "area",
"kind": "variable",
"docComment": "Area in square units.",
"typeSignature": "number",
"modifiers": [
"getter"
]
},
{
"name": "size",
"kind": "variable",
"docComment": "Longest side; setting it makes the rectangle a square.",
"typeSignature": "number",
"modifiers": [
"getter",
"setter"
]
}
]
},
{
"name": "describe_shape",
"kind": "function",
"docComment": "Describe a shape for display.",
"typeSignature": "(shape: HasArea, options?: { precision?: number | undefined; label?: string | undefined; }): string",
"sourceLine": 127,
"parameters": [
{
"name": "shape",
"type": "HasArea",
"description": "the shape to describe"
},
{
"name": "options",
"type": "{ precision?: number | undefined; label?: string | undefined; }",
"description": "formatting options",
"defaultValue": "{}",
"propertyDescriptions": {
"precision": "decimal places for the area",
"label": "prefix for the description"
}
}
],
"returnType": "string",
"returnDescription": "a human-readable description"
},
{
"name": "UNIT_SQUARE",
"kind": "variable",
"docComment": "Unit square corners as a readonly tuple (const assertion).",
"typeSignature": "readonly [{ readonly x: 0; readonly y: 0; }, { readonly x: 1; readonly y: 0; }, { readonly x: 1; readonly y: 1; }, { readonly x: 0; readonly y: 1; }]",
"sourceLine": 133
}
],
"moduleComment": "Geometric shapes demonstrating classes, interfaces, enums, function\noverloads, const assertions, and richer JSDoc tags.",
"dependents": [
"index.ts"
]
}