/** * Geometric shapes demonstrating classes, interfaces, enums, a union type * alias, function overloads, const assertions, and richer JSDoc tags * (`@deprecated` among them). * @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; } /** What `shapeArea` measures: a shape, or a circle's radius. */ export type ShapeInput = HasArea | 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 `shapeArea` */ 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 #drawCount = 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 countDraw(): number { return ++this.#drawCount; } } /** * Compute the area of a shape. * @param shape - the shape to measure * @returns the shape's area * @example * ```ts * shapeArea(new Rectangle(2, 3)) // 6 * shapeArea(1) // Math.PI * ``` */ export function shapeArea(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 shapeArea(radius: number): number; export function shapeArea(shapeOrRadius: ShapeInput): number { return typeof shapeOrRadius === 'number' ? Math.PI * shapeOrRadius ** 2 : shapeOrRadius.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 function describeShape( shape: HasArea, options: { precision?: number; label?: string } = {} ): string { return `${options.label ?? 'shape'}: area ${shape.area.toFixed(options.precision ?? 2)}`; } /** * Compute a rectangle's area from its dimensions. * @param width - rectangle width * @param height - rectangle height * @returns the area * @deprecated use `shapeArea(new Rectangle(width, height))` */ export function rectangleArea(width: number, height: number): number { return width * height; } /** 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": "shapeArea", "kind": "function", "docComment": "Compute the area of a shape.", "typeSignature": "(shape: HasArea): number", "sourceLine": 110, "examples": [ "```ts\nshapeArea(new Rectangle(2, 3)) // 6\nshapeArea(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": "describeShape", "kind": "function", "docComment": "Describe a shape for display.", "typeSignature": "(shape: HasArea, options?: { precision?: number | undefined; label?: string | undefined; }): string", "sourceLine": 131, "parameters": [ { "name": "shape", "type": "HasArea", "description": "the shape to describe" }, { "name": "options", "type": "{ precision?: number | undefined; label?: string | undefined; }", "optional": true, "description": "formatting options", "defaultValue": "{}", "propertyDescriptions": { "precision": "decimal places for the area", "label": "prefix for the description" } } ], "returnType": "string", "returnDescription": "a human-readable description" }, { "name": "rectangleArea", "kind": "function", "docComment": "Compute a rectangle's area from its dimensions.", "typeSignature": "(width: number, height: number): number", "sourceLine": 145, "deprecatedMessage": "use `shapeArea(new Rectangle(width, height))`", "parameters": [ { "name": "width", "type": "number", "description": "rectangle width" }, { "name": "height", "type": "number", "description": "rectangle height" } ], "returnType": "number", "returnDescription": "the area" }, { "name": "ShapeKind", "kind": "enum", "docComment": "Supported shape categories.", "typeSignature": "ShapeKind", "sourceLine": 9, "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": 15, "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": 23, "members": [ { "name": "area", "kind": "variable", "docComment": "Area in square units.", "typeSignature": "number", "modifiers": [ "readonly" ] } ] }, { "name": "ShapeInput", "kind": "type", "docComment": "What `shapeArea` measures: a shape, or a circle's radius.", "typeSignature": "ShapeInput", "sourceLine": 29, "typeInfo": { "kind": "union", "alias": "ShapeInput", "members": [ { "kind": "reference", "name": "HasArea" }, { "kind": "intrinsic", "text": "number" } ] } }, { "name": "DrawOptions", "kind": "interface", "docComment": "Options for drawing a shape outline.", "typeSignature": "DrawOptions", "sourceLine": 32, "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": 47, "seeAlso": [ "`shapeArea`" ], "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", "mutates": { "this": "" }, "parameters": [ { "name": "factor", "type": "number", "description": "multiplier applied to width and height" } ], "returnType": "void" }, { "name": "countDraw", "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": "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": 150 } ], "moduleComment": "Geometric shapes demonstrating classes, interfaces, enums, a union type\nalias, function overloads, const assertions, and richer JSDoc tags\n(`@deprecated` among them).", "dependents": [ "index.ts" ] }