or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

context-metadata.mdcore-constructs.mddependency-management.mdindex.mdtree-nodes.mdvalidation.md
tile.json

tessl/npm-constructs

A programming model for software-defined state through composable building blocks

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/constructs@10.4.x

To install, run

npx @tessl/cli install tessl/npm-constructs@10.4.0

index.mddocs/

Constructs

Constructs is a TypeScript library providing a programming model for software-defined state through composable building blocks. It enables developers to define, compose, and manage complex system state as hierarchical construct trees. Constructs are the foundation for higher-level frameworks like AWS CDK, CDK8s, and CDKTF.

Package Information

  • Package Name: constructs
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install constructs

Core Imports

import { 
  Construct, 
  RootConstruct, 
  Node, 
  IConstruct, 
  IDependable,
  Dependable,
  DependencyGroup,
  ConstructOrder,
  MetadataEntry,
  MetadataOptions,
  IValidation
} from "constructs";

For CommonJS:

const { 
  Construct, 
  RootConstruct, 
  Node 
} = require("constructs");

Basic Usage

import { Construct, RootConstruct } from "constructs";

// Create a root construct
const app = new RootConstruct("MyApp");

// Create child constructs
const database = new Construct(app, "Database");
const api = new Construct(app, "API");
const frontend = new Construct(api, "Frontend");

// Navigate the construct tree
console.log(frontend.node.path); // "API/Frontend"
console.log(frontend.node.root === app); // true
console.log(app.node.children.length); // 2

// Add dependencies
api.node.addDependency(database);

// Set context for configuration
app.node.setContext("environment", "production");
const env = api.node.getContext("environment"); // "production"

Architecture

The constructs library is built around several key components:

  • Construct Tree: Hierarchical structure where each construct represents a piece of system state
  • Node System: Each construct has an associated Node that manages tree relationships and metadata
  • Dependency Management: Framework for declaring ordering dependencies between constructs
  • Context System: Hierarchical configuration and data sharing mechanism
  • Metadata System: Arbitrary data attachment for debugging and tooling
  • Validation Framework: Pluggable validation system for construct validation

Capabilities

Core Construct System

Foundation classes for building construct trees with hierarchical relationships, tree navigation, and lifecycle management.

class Construct implements IConstruct {
  constructor(scope: Construct, id: string);
  readonly node: Node;
  toString(): string;
  static isConstruct(x: any): boolean;
}

class RootConstruct extends Construct {
  constructor(id?: string);
}

interface IConstruct extends IDependable {
  readonly node: Node;
}

Core Construct System

Tree Node Management

The Node class provides comprehensive tree management, navigation, and metadata operations for constructs.

class Node {
  readonly id: string;
  readonly scope?: IConstruct;
  readonly path: string;
  readonly addr: string;
  readonly children: IConstruct[];
  readonly root: IConstruct;
  readonly scopes: IConstruct[];
  
  findChild(id: string): IConstruct;
  tryFindChild(id: string): IConstruct | undefined;
  findAll(order?: ConstructOrder): IConstruct[];
  
  static readonly PATH_SEP: string;
}

Tree Node Management

Dependency Management

System for declaring and managing ordering dependencies between constructs, enabling controlled deployment sequences.

interface IDependable {
  // Marker interface for dependable objects
}

abstract class Dependable {
  abstract readonly dependencyRoots: IConstruct[];
  static implement(instance: IDependable, trait: Dependable): void;
  static of(instance: IDependable): Dependable;
}

class DependencyGroup implements IDependable {
  constructor(...deps: IDependable[]);
  add(...scopes: IDependable[]): void;
}

Dependency Management

Context and Metadata

Context system for hierarchical configuration sharing and metadata system for arbitrary data attachment.

// Context methods on Node
setContext(key: string, value: any): void;
getContext(key: string): any;
tryGetContext(key: string): any;
getAllContext(defaults?: object): any;

// Metadata methods on Node  
addMetadata(type: string, data: any, options?: MetadataOptions): void;
readonly metadata: MetadataEntry[];

interface MetadataEntry {
  readonly type: string;
  readonly data: any;
  readonly trace?: string[];
}

interface MetadataOptions {
  readonly stackTrace?: boolean;
  readonly traceFromFunction?: any;
}

Context and Metadata

Validation System

Framework for adding custom validation logic to constructs with error collection and reporting.

interface IValidation {
  validate(): string[];
}

// Validation methods on Node
addValidation(validation: IValidation): void;
validate(): string[];

Validation System

Types

enum ConstructOrder {
  /**
   * Depth-first, pre-order
   */
  PREORDER = 0,
  
  /**
   * Depth-first, post-order (leaf nodes first)
   */
  POSTORDER = 1
}

interface MetadataEntry {
  readonly type: string;
  readonly data: any;
  readonly trace?: string[];
}

interface MetadataOptions {
  readonly stackTrace?: boolean;
  readonly traceFromFunction?: any;
}

interface IValidation {
  validate(): string[];
}

interface IConstruct extends IDependable {
  readonly node: Node;
}

interface IDependable {
  // Marker interface
}