This directory contains practical TypeScript examples demonstrating SharpTS capabilities, from basic utilities to advanced interoperability with C#.

All examples can be run using the SharpTS interpreter:

sharpts Examples/<example-name>.ts [arguments]

Or compiled ahead-of-time to .NET assemblies:

sharpts --compile Examples/<example-name>.ts
dotnet Examples/<example-name>.dll [arguments]

What it does: Generates multiple checksums (MD5, SHA1, SHA256, SHA512) for any file.

Usage:

sharpts Examples/file-hasher.ts <filepath>

# Example
sharpts Examples/file-hasher.ts README.md

Demonstrates:

• crypto module: createHash(), .update(), .digest()
• fs module: readFileSync(), existsSync(), statSync()
• path module: basename(), resolve()
• Command-line argument processing via process.argv
• String manipulation and formatting
• For-of loops with arrays

Key Features:

• Displays file size in human-readable format (B, KB, MB, GB)
• Validates file existence and type
• Computes four hash algorithms in one pass
• Clean tabular output

What it does: Automatically organizes files in a directory by moving them into categorized folders based on file extension (images, documents, code, archives, etc.).

Usage:

sharpts Examples/file-organizer.ts <directory> [--dry-run]

# Example - preview changes without moving files
sharpts Examples/file-organizer.ts ~/Downloads --dry-run

# Example - actually organize files
sharpts Examples/file-organizer.ts ~/Downloads

Demonstrates:

• fs module: readdirSync(), statSync(), mkdirSync(), renameSync(), existsSync()
• path module: join(), extname(), basename()
• Object literals for mapping data
• Property access syntax with bracket notation
• Conditional logic and directory creation
• Safe "dry run" pattern for file operations

Key Features:

• Pre-configured categories for common file types
• Creates destination folders automatically
• Dry-run mode to preview changes
• Falls back to generic categorization for unknown extensions
• Skips files without extensions
• Summary statistics

What it does: Interactive password generator with customizable character sets and cryptographically secure randomness.

Usage:

sharpts Examples/password-generator.ts [length]

# Example - interactive mode
sharpts Examples/password-generator.ts

# Example - specify length upfront
sharpts Examples/password-generator.ts 24

Demonstrates:

• crypto module: randomBytes(), randomInt()
• readline module: questionSync() for user input
• String concatenation and character manipulation
• Interactive CLI with yes/no questions
• Input validation and error handling
• Mathematical calculations (entropy calculation using Math.log())

Key Features:

• Generates 5 password options at once
• Customizable character sets (lowercase, uppercase, digits, symbols)
• Calculates password entropy in bits
• Validates password length (4-128 characters)
• Uses cryptographically secure random number generation

What it does: Displays comprehensive system information including OS details, memory usage, CPU info, and process metrics.

Usage:

sharpts Examples/system-info.ts

Demonstrates:

• os module: platform(), arch(), hostname(), cpus(), totalmem(), freemem(), homedir(), tmpdir(), userInfo(), type(), release()
• process module: pid, version, cwd(), env, argv, uptime(), memoryUsage()
• Number formatting and calculations
• Working with arrays (CPU cores)
• Accessing object properties
• Environment variable access
• String truncation for display

Key Features:

• Memory statistics with percentage calculation
• CPU information (cores, model, speed)
• Process uptime formatting (hours, minutes, seconds)
• Selective environment variable display
• Human-readable memory sizes (GB and MB)

What it does: Parse, build, and manipulate URLs with an interactive command-line interface.

Usage:

# Parse a URL from command line
sharpts Examples/url-toolkit.ts "https://example.com/path?key=value"

# Interactive mode
sharpts Examples/url-toolkit.ts

Interactive Commands:

• parse <url> - Parse and display URL components
• encode <string> - URL encode a string
• decode <string> - URL decode a string
• resolve <base> <rel> - Resolve a relative URL against a base URL
• build - Build a URL interactively
• quit - Exit

Demonstrates:

• url module: parse(), resolve()
• querystring module: parse(), stringify(), escape(), unescape()
• readline module: Interactive input loops
• String methods: startsWith(), substring(), trim(), split()
• Object key iteration with Object.keys()
• While loops and interactive REPL pattern
• Optional/nullable handling with || operator

Key Features:

• Full URL parsing (protocol, host, port, pathname, query, hash)
• Query string parameter extraction
• Interactive URL builder
• URL encoding/decoding utilities
• Relative URL resolution

What it does: Comprehensive source code analysis tool that scans directories recursively and generates statistics about code files.

Usage:

sharpts Examples/SourceAnalyzer/source-analyzer.ts [directory] [--help]

# Example - analyze current directory
sharpts Examples/SourceAnalyzer/source-analyzer.ts

# Example - analyze specific directory
sharpts Examples/SourceAnalyzer/source-analyzer.ts ./src

# Example - show help
sharpts Examples/SourceAnalyzer/source-analyzer.ts --help

Demonstrates:

• TypeScript interfaces for type safety
• Complex directory traversal with recursion
• File filtering and pattern matching
• Multi-line string processing
• Advanced function detection heuristics
• Table formatting with padded strings
• Modular code organization with logical sections
• Process exit codes with process.exit()
• Path manipulation: isAbsolute(), join()

Key Features:

• Supports multiple file types (.ts, .tsx, .js, .jsx, .css, .html, .json)
• Auto-excludes common directories (node_modules, .git, dist, build, obj, bin)
• Counts total lines, non-empty lines, and functions
• Function detection for multiple patterns (function keyword, arrow functions, class methods)
• Formatted table output with summary statistics
• Handles Windows reserved filenames safely

What it does: Demonstrates how to consume SharpTS-compiled TypeScript assemblies from C# applications using runtime reflection.

This is a more complex example with its own subdirectory structure and build process.

Structure:

Interop/
├── TypeScript/
│   └── Library.ts        # TypeScript source with example classes
├── CompiledTS/           # Generated assemblies
│   ├── Library.dll       # Compiled TypeScript (generated)
│   └── SharpTS.dll       # Runtime dependency (copied)
├── Program.cs            # C# consumer demonstrating interop
├── build.ps1             # Automated build script
├── README.md             # Detailed interop documentation
└── SharpTS.Example.Interop.csproj

Build and Run:

# From Examples/Interop directory
.\build.ps1

TypeScript Features Demonstrated:

• Classes with constructors and methods
• Instance and static members
• Property accessors
• Class inheritance with extends
• Method overriding
• Top-level functions
• Arrays and collections

C# Interop Patterns:

• Loading compiled TypeScript assemblies with Assembly.LoadFrom()
• Type discovery via Assembly.GetType()
• Instance creation with Activator.CreateInstance()
• Property access via PropertyInfo (PascalCase naming)
• Method invocation with MethodInfo.Invoke()
• Static member access with BindingFlags.Static
• Working with inheritance hierarchies
• Accessing top-level functions via $Program class

Type Mapping:

See Examples/Interop/README.md for detailed documentation.

What it does: Times four small CPU-bound workloads using perf_hooks, then runs two phases under performance.mark() / performance.measure(). Output shows ms and ops/sec per workload and a grand-total time.

Usage:

sharpts Examples/benchmark.ts                                 # interpreted
sharpts --compile Examples/benchmark.ts -o b.dll && dotnet b.dll   # compiled

Demonstrates:

• perf_hooks module: performance.now(), performance.mark(), performance.measure(), performance.getEntriesByType(), performance.timeOrigin
• Warm-up loops, iteration scaling, ops/sec reporting
• Same-file comparison between tree-walking interpretation and compiled IL — compiled typically runs ~100× faster on the numeric loops

Key Features:

• Runs identically in both modes; the output differs only in absolute timings
• Ships iteration counts tuned so interpreted completes in a few seconds — compiled is effectively instant

What it does: Demonstrates the inbound direction of .NET interop — TypeScript consuming .NET types via the @DotNetType decorator. Shows StringBuilder, Guid.newGuid(), Convert.toInt32 with an @DotNetOverload hint, Task.Run with a TypeScript closure as a .NET Action, and AppDomain.ProcessExit with a DOM-style addEventListener.

Usage:

sharpts Examples/dotnet-types.ts                                     # interpreted
sharpts --compile Examples/dotnet-types.ts -o d.dll && dotnet d.dll  # compiled (standalone DLL)

Runs identically in both modes. The compiled DLL is fully standalone — it doesn't need SharpTS.dll alongside.

Demonstrates:

• @DotNetType("System.Text.StringBuilder") — instance methods and properties
• @DotNetType("System.Guid") — static methods
• @DotNetOverload("int") — pinning the Convert.ToInt32(int) overload so 3.7 → 3 instead of the default ToInt32(double) 3.7 → 4
• Delegates — a TS arrow function passed as System.Action to Task.Run
• Events — subscribing to System.AppDomain.ProcessExit via addEventListener; the handler fires at shutdown

See dotnet-types.md for the full surface of the decorator and related features like @DotNetOverload and the threading contract for delegate callbacks.

What it does: Consumes the real uuid package from node_modules. Generates v4 UUIDs, validates strings, reads the NIL constant, parses a UUID to its 16-byte form, and does a 1000-iteration uniqueness check.

Setup (one-time):

cd Examples/NpmUuid
npm install

Usage:

sharpts Examples/NpmUuid/npm-uuid.ts                            # interpreted
sharpts --compile Examples/NpmUuid/npm-uuid.ts -o u.dll && dotnet u.dll  # compiled

Demonstrates:

• Named ESM import { v4, validate, ... } from 'uuid' against a real npm package
• Multiple named exports backed by Babel-style accessor descriptors
• Working against Uint8Array return values

What it does: A demonstration HTTP server with routing, static HTML pages, and dynamic JSON API endpoints. Showcases SharpTS's HTTP server capabilities.

Usage:

# Start server on default port 3000
sharpts Examples/web-server.ts

# Start server on custom port
sharpts Examples/web-server.ts 8080

# Show help
sharpts Examples/web-server.ts --help

Demonstrates:

• http module: createServer(), server events (on('listening'), on('error'))
• Request properties: method, url, headers, socket
• Response methods: writeHead(), end()
• url module: parse() for URL parsing
• querystring module: parse() for query string parsing
• Content-Type headers (text/html, application/json)
• HTTP status codes (200, 404)
• Path parameter extraction from URLs

Key Features:

• Multiple route handlers with pattern matching
• Static HTML pages with inline CSS styling
• Dynamic JSON API endpoints
• Request logging to console
• XSS prevention via HTML escaping
• Personalized greetings with path parameters
• Echo endpoint showing request details

Routes:

This table shows which SharpTS/TypeScript features each example demonstrates. Abbreviations: fh = file-hasher, fo = file-organizer, pg = password-generator, si = system-info, ut = url-toolkit, sa = source-analyzer, ip = interop, ws = web-server, bm = benchmark, dn = dotnet-types, nu = npm-uuid.

SharpTS provides Node.js-compatible built-in modules:

File System (fs)

• readFileSync() - Read file contents
• readdirSync() - List directory entries
• statSync() - Get file/directory stats
• existsSync() - Check if path exists
• mkdirSync() - Create directory
• renameSync() - Move/rename files

Path (path)

• join() - Combine path segments
• resolve() - Resolve absolute path
• basename() - Get filename from path
• extname() - Get file extension
• isAbsolute() - Check if path is absolute

Crypto (crypto)

• createHash() - Create hash instance
• randomBytes() - Generate random bytes
• randomInt() - Generate random integer

OS (os)

• platform(), arch(), type(), release() - OS information
• hostname() - System hostname
• cpus() - CPU information
• totalmem(), freemem() - Memory information
• homedir(), tmpdir() - Directory paths
• userInfo() - Current user information

Process (process)

• argv - Command-line arguments
• env - Environment variables
• cwd() - Current working directory
• pid - Process ID
• version - Node version
• uptime() - Process uptime
• memoryUsage() - Process memory usage
• exit() - Exit with code

URL (url)

• parse() - Parse URL string
• resolve() - Resolve relative URLs

Query String (querystring)

• parse() - Parse query string
• stringify() - Build query string
• escape() - URL encode
• unescape() - URL decode

Readline (readline)

• questionSync() - Synchronous user input

HTTP (http)

• createServer(handler) - Create an HTTP server
• Server methods: listen(port, callback?), close(callback?)
• Server events: on('listening'), on('error'), on('request')
• Server properties: listening, address()
• Request properties: method, url, headers, socket, httpVersion
• Response methods: writeHead(status, headers?), write(data), end(data?), setHeader(name, value)
• Response properties: statusCode, statusMessage, headersSent

Interpreted mode (faster for development):

sharpts Examples/<example>.ts

Compiled mode (better performance, standalone executable):

# Compile
sharpts --compile Examples/<example>.ts

# Run the compiled assembly
dotnet Examples/<example>.dll

View help for examples: Most examples display usage information when run without arguments:

sharpts Examples/file-hasher.ts

Recommended order for exploring examples:

1. system-info.ts - Start here to see basic built-in modules
2. file-hasher.ts - Learn file operations and crypto
3. password-generator.ts - Explore user input and randomness
4. file-organizer.ts - Practice file system manipulation
5. url-toolkit.ts - Interactive CLI patterns
6. web-server.ts - HTTP server with routing and APIs
7. source-analyzer.ts - Complex application with interfaces
8. benchmark.ts - perf_hooks and an interpreted-vs-compiled comparison
9. NpmUuid/npm-uuid.ts - Consuming a real npm package
10. dotnet-types.ts - Inbound interop: calling .NET BCL from TypeScript
11. Interop/ - Outbound interop: consuming compiled TS from C#

When creating new examples:

1. Add a comment header explaining usage and demonstrated features
2. Include a main() function for organization
3. Use process.argv.slice(2) for command-line arguments
4. Provide helpful error messages
5. Show usage information when run without required arguments
6. Consider adding both interpreted and compiled usage examples

Example template:

// My Example - Brief description
// Usage: sharpts Examples/my-example.ts <args>
//
// Demonstrates: feature1, feature2, feature3

import module from 'module';
import process from 'process';

function main(): void {
    const args = process.argv.slice(2);

    if (args.length === 0) {
        console.log('My Example - Description');
        console.log('');
        console.log('Usage: sharpts Examples/my-example.ts <args>');
        return;
    }

    // Your code here
}

main();

• SharpTS README (../README.md) - Project overview and build instructions
• CLAUDE.md (../CLAUDE.md) - Detailed architecture and development guide
• Test Suite (../SharpTS.Tests/) - Comprehensive feature tests
• Interop Documentation (Interop/README.md) - C# interop details

Have an interesting example? Consider:

• Demonstrating a specific SharpTS feature
• Solving a practical problem
• Showing idiomatic TypeScript patterns
• Highlighting interop capabilities

Keep examples focused, well-documented, and easy to run.