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

core-constructs.mddocs/

Core Construct System

The core construct system provides the foundational classes for building hierarchical construct trees. Each construct represents a piece of system state and can contain child constructs to form complex compositions.

Capabilities

Construct Class

The main building block class representing a piece of system state that can be composed with other constructs.

/**
 * Represents the building block of the construct graph.
 * All constructs besides the root construct must be created within the scope of another construct.
 */
class Construct implements IConstruct {
  /**
   * Creates a new construct node.
   * @param scope The scope in which to define this construct
   * @param id The scoped construct ID. Must be unique amongst siblings. If the ID includes a path separator (`/`), then it will be replaced by double dash `--`.
   */
  constructor(scope: Construct, id: string);
  
  /** The tree node. */
  readonly node: Node;
  
  /** Returns a string representation of this construct. */
  toString(): string;
  
  /**
   * Checks if `x` is a construct.
   * Use this method instead of `instanceof` to properly detect `Construct` instances, 
   * even when the construct library is symlinked.
   * @param x Any object
   * @returns true if `x` is an object created from a class which extends `Construct`.
   */
  static isConstruct(x: any): boolean;
}

Usage Examples:

import { Construct, RootConstruct } from "constructs";

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

// Create child constructs  
const vpc = new Construct(app, "VPC");
const database = new Construct(vpc, "Database");
const webServer = new Construct(vpc, "WebServer");

// Check if object is a construct
console.log(Construct.isConstruct(database)); // true
console.log(Construct.isConstruct({})); // false

// String representation
console.log(database.toString()); // "VPC/Database"
console.log(app.toString()); // "<root>"

RootConstruct Class

Special construct class designed to serve as the root of a construct tree, with no parent scope.

/**
 * Creates a new root construct node.
 * The root construct represents the top of the construct tree and is not contained within a parent scope itself.
 * For root constructs, the id is optional.
 */
class RootConstruct extends Construct {
  /**
   * Creates a new root construct node.
   * @param id The scoped construct ID. Must be unique amongst siblings. If the ID includes a path separator (`/`), then it will be replaced by double dash `--`.
   */
  constructor(id?: string);
  
  /** The tree node. */
  readonly node: Node;
  
  /** Returns a string representation of this construct. */
  toString(): string;
  
  /**
   * Checks if `x` is a construct.
   * @param x Any object
   * @returns true if `x` is an object created from a class which extends `Construct`.
   */
  static isConstruct(x: any): boolean;
}

Usage Examples:

import { RootConstruct, Construct } from "constructs";

// Create root constructs
const app1 = new RootConstruct(); // Empty ID
const app2 = new RootConstruct("MyApplication");

// Root constructs have empty or specified paths
console.log(app1.node.path); // ""
console.log(app2.node.path); // ""
console.log(app1.node.scope); // undefined
console.log(app2.node.scope); // undefined

// Add children to root
const service = new Construct(app2, "Service");
console.log(service.node.path); // "Service"
console.log(service.node.root === app2); // true

IConstruct Interface

Base interface that all constructs must implement, extending IDependable to enable dependency management.

/**
 * Represents a construct.
 */
interface IConstruct extends IDependable {
  /** The tree node. */
  readonly node: Node;
}

Construct ID Handling

Construct IDs are automatically sanitized to handle path separators and ensure valid tree structures.

Usage Examples:

import { Construct, RootConstruct } from "constructs";

const app = new RootConstruct();

// Path separators are replaced with double dashes
const construct1 = new Construct(app, "my/path/to/construct");
console.log(construct1.node.id); // "my--path--to--construct"

// Various characters are allowed in IDs
const construct2 = new Construct(app, "Valid_ID-123");
const construct3 = new Construct(app, "spaces are allowed");
const construct4 = new Construct(app, "special.chars\\OK");

// Empty IDs only allowed for root constructs
try {
  new Construct(app, ""); // Throws error: Only root constructs may have an empty ID
} catch (error) {
  console.log(error.message);
}

Construct Tree Relationships

All constructs automatically participate in a hierarchical tree structure with parent-child relationships.

Usage Examples:

import { Construct, RootConstruct } from "constructs";

const app = new RootConstruct("App");
const frontend = new Construct(app, "Frontend");
const backend = new Construct(app, "Backend");
const database = new Construct(backend, "Database");

// Navigate parent-child relationships
console.log(frontend.node.scope === app); // true
console.log(backend.node.children.length); // 1
console.log(backend.node.children[0] === database); // true

// Access tree structure
console.log(database.node.scopes); // [app, backend, database]
console.log(database.node.root === app); // true
console.log(app.node.children); // [frontend, backend]

// Get unique addresses
console.log(database.node.addr); // e.g., "c83a2846e506bcc5f10682b564084bca2d275709ee"
console.log(frontend.node.addr !== backend.node.addr); // true