@cubis/foundry 0.3.10

package/Ai Agent Workflow/skills/javascript-pro/references/modern-syntax.md

@@ -0,0 +1,272 @@
+# Modern JavaScript Syntax (ES2023+)
+
+## Optional Chaining and Nullish Coalescing
+
+```javascript
+// Optional chaining - safe property access
+const userName = user?.profile?.name;
+const firstItem = items?.[0];
+const result = api?.fetchData?.();
+
+// Nullish coalescing - default only for null/undefined
+const port = config.port ?? 3000;
+const name = user.name ?? 'Anonymous';
+
+// Combining both patterns
+const displayName = user?.profile?.name ?? user?.email ?? 'Guest';
+
+// Optional chaining with delete
+delete user?.temporaryData?.cache;
+```
+
+## Private Class Fields
+
+```javascript
+class BankAccount {
+  // Private fields
+  #balance = 0;
+  #accountNumber;
+
+  // Private method
+  #validateAmount(amount) {
+    if (amount <= 0) throw new Error('Invalid amount');
+  }
+
+  constructor(accountNumber, initialBalance = 0) {
+    this.#accountNumber = accountNumber;
+    this.#balance = initialBalance;
+  }
+
+  deposit(amount) {
+    this.#validateAmount(amount);
+    this.#balance += amount;
+    return this.#balance;
+  }
+
+  getBalance() {
+    return this.#balance;
+  }
+}
+
+// Static private fields
+class Config {
+  static #apiKey = process.env.API_KEY;
+
+  static getApiKey() {
+    return this.#apiKey;
+  }
+}
+```
+
+## Top-Level Await
+
+```javascript
+// No need for async IIFE wrapper
+const data = await fetch('/api/config').then(r => r.json());
+const db = await connectDatabase(data.dbUrl);
+
+// Dynamic imports with await
+const module = await import(`./modules/${moduleName}.js`);
+
+// Error handling at top level
+try {
+  const config = await loadConfig();
+  startServer(config);
+} catch (error) {
+  console.error('Failed to start:', error);
+  process.exit(1);
+}
+```
+
+## Array Methods (Modern)
+
+```javascript
+// at() - negative indexing
+const last = items.at(-1);
+const secondLast = items.at(-2);
+
+// findLast() and findLastIndex()
+const lastEven = numbers.findLast(n => n % 2 === 0);
+const lastIndex = numbers.findLastIndex(n => n > 10);
+
+// toSorted(), toReversed(), toSpliced() - non-mutating
+const sorted = items.toSorted((a, b) => a - b);
+const reversed = items.toReversed();
+const spliced = items.toSpliced(1, 2, 'new');
+
+// with() - replace at index
+const updated = items.with(2, 'newValue');
+
+// flatMap() for transform and flatten
+const nestedResults = users.flatMap(user => user.posts);
+```
+
+## Object and String Enhancements
+
+```javascript
+// Object.groupBy() - group array elements
+const groupedByAge = Object.groupBy(users, user => user.age);
+const groupedByStatus = Object.groupBy(orders, o => o.status);
+
+// Object.hasOwn() - safer hasOwnProperty
+if (Object.hasOwn(obj, 'key')) {
+  // safer than obj.hasOwnProperty('key')
+}
+
+// String.prototype.at()
+const firstChar = str.at(0);
+const lastChar = str.at(-1);
+
+// replaceAll()
+const cleaned = text.replaceAll('old', 'new');
+const sanitized = input.replaceAll(/[<>]/g, '');
+```
+
+## WeakRef and FinalizationRegistry
+
+```javascript
+// WeakRef - hold weak references to objects
+class Cache {
+  #cache = new Map();
+
+  set(key, value) {
+    this.#cache.set(key, new WeakRef(value));
+  }
+
+  get(key) {
+    const ref = this.#cache.get(key);
+    return ref?.deref(); // undefined if GC'd
+  }
+}
+
+// FinalizationRegistry - cleanup callbacks
+const registry = new FinalizationRegistry((heldValue) => {
+  console.log(`Cleanup: ${heldValue}`);
+  // Release resources
+});
+
+class Resource {
+  constructor(id) {
+    this.id = id;
+    registry.register(this, id, this);
+  }
+
+  dispose() {
+    registry.unregister(this);
+  }
+}
+```
+
+## Logical Assignment Operators
+
+```javascript
+// ||= - assign if falsy
+config.timeout ||= 5000;
+user.name ||= 'Anonymous';
+
+// &&= - assign if truthy
+user.profile &&= sanitize(user.profile);
+
+// ??= - assign if nullish
+options.port ??= 3000;
+settings.theme ??= 'dark';
+```
+
+## Numeric Separators and BigInt
+
+```javascript
+// Numeric separators for readability
+const billion = 1_000_000_000;
+const bytes = 0xFF_EC_DE_5E;
+const trillion = 1_000_000_000_000n;
+
+// BigInt for large integers
+const hugeNumber = 9007199254740991n;
+const result = hugeNumber + 1n;
+const mixed = BigInt(123) + 456n;
+
+// BigInt operations
+const divided = 10n / 3n; // 3n (truncates)
+const power = 2n ** 64n;
+```
+
+## Pattern Matching (Stage 3 Proposal)
+
+```javascript
+// Using switch with enhanced patterns (when available)
+function processValue(value) {
+  switch (true) {
+    case typeof value === 'string':
+      return value.toUpperCase();
+    case typeof value === 'number':
+      return value * 2;
+    case Array.isArray(value):
+      return value.length;
+    default:
+      return null;
+  }
+}
+
+// Object destructuring patterns
+function handleResponse({ status, data, error }) {
+  if (error) throw error;
+  if (status === 200) return data;
+  return null;
+}
+```
+
+## Iterator Helpers (Stage 3)
+
+```javascript
+// When available - chaining iterator operations
+const result = [1, 2, 3, 4, 5]
+  .values()
+  .map(x => x * 2)
+  .filter(x => x > 5)
+  .toArray();
+
+// Custom iterators
+const range = {
+  *[Symbol.iterator]() {
+    for (let i = 0; i < 10; i++) {
+      yield i;
+    }
+  }
+};
+
+for (const num of range) {
+  console.log(num);
+}
+```
+
+## Temporal API (Stage 3)
+
+```javascript
+// Modern date/time handling (when available)
+import { Temporal } from '@js-temporal/polyfill';
+
+const now = Temporal.Now.instant();
+const date = Temporal.PlainDate.from('2024-01-15');
+const time = Temporal.PlainTime.from('14:30:00');
+
+// Duration calculations
+const duration = Temporal.Duration.from({ hours: 2, minutes: 30 });
+const later = now.add(duration);
+
+// Timezone handling
+const zonedTime = now.toZonedDateTimeISO('America/New_York');
+```
+
+## Quick Reference
+
+| Feature | ES Version | Syntax |
+|---------|-----------|--------|
+| Optional chaining | ES2020 | `obj?.prop` |
+| Nullish coalescing | ES2020 | `value ?? default` |
+| Private fields | ES2022 | `#fieldName` |
+| Top-level await | ES2022 | `await import()` |
+| Logical assignment | ES2021 | `x ??= y` |
+| Array.at() | ES2022 | `arr.at(-1)` |
+| Object.hasOwn() | ES2022 | `Object.hasOwn(obj, 'key')` |
+| Array.findLast() | ES2023 | `arr.findLast(fn)` |
+| toSorted() | ES2023 | `arr.toSorted()` |

package/Ai Agent Workflow/skills/javascript-pro/references/modules.md

@@ -0,0 +1,357 @@
+# Module Systems
+
+## ES Modules (ESM)
+
+```javascript
+// Named exports
+export const PI = 3.14159;
+export function add(a, b) {
+  return a + b;
+}
+
+export class Calculator {
+  multiply(a, b) {
+    return a * b;
+  }
+}
+
+// Default export
+export default class Database {
+  async connect() {
+    // implementation
+  }
+}
+
+// Re-exports
+export { add, multiply } from './math.js';
+export * from './utils.js';
+export * as helpers from './helpers.js';
+```
+
+## Import Patterns
+
+```javascript
+// Named imports
+import { add, multiply } from './math.js';
+import { add as addition } from './math.js';
+
+// Default import
+import Database from './database.js';
+
+// Namespace import
+import * as math from './math.js';
+math.add(1, 2);
+
+// Mixed imports
+import Database, { connect, disconnect } from './database.js';
+
+// Side-effect only import
+import './polyfills.js';
+
+// Type-only imports (for documentation)
+/** @typedef {import('./types.js').User} User */
+```
+
+## Dynamic Imports
+
+```javascript
+// Basic dynamic import
+const module = await import('./module.js');
+module.default();
+
+// Conditional loading
+const loadFeature = async (feature) => {
+  if (feature === 'advanced') {
+    const { AdvancedFeature } = await import('./advanced.js');
+    return new AdvancedFeature();
+  }
+  const { BasicFeature } = await import('./basic.js');
+  return new BasicFeature();
+};
+
+// Code splitting by route
+const router = {
+  '/home': () => import('./pages/home.js'),
+  '/about': () => import('./pages/about.js'),
+  '/profile': () => import('./pages/profile.js')
+};
+
+const loadPage = async (route) => {
+  const module = await router[route]();
+  return module.default;
+};
+
+// Lazy loading with caching
+const moduleCache = new Map();
+
+const importWithCache = async (path) => {
+  if (moduleCache.has(path)) {
+    return moduleCache.get(path);
+  }
+  const module = await import(path);
+  moduleCache.set(path, module);
+  return module;
+};
+```
+
+## Package.json Configuration
+
+```json
+{
+  "name": "my-package",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./utils": {
+      "import": "./dist/utils.mjs",
+      "require": "./dist/utils.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "imports": {
+    "#utils": "./src/utils/index.js",
+    "#constants": "./src/constants.js"
+  }
+}
+```
+
+## Conditional Exports
+
+```javascript
+// package.json with conditional exports
+{
+  "exports": {
+    ".": {
+      "node": "./dist/node.js",
+      "browser": "./dist/browser.js",
+      "default": "./dist/index.js"
+    },
+    "./feature": {
+      "development": "./src/feature.dev.js",
+      "production": "./dist/feature.prod.js"
+    }
+  }
+}
+
+// Usage in code
+import api from 'my-package'; // Resolves based on environment
+import feature from 'my-package/feature'; // Conditional based on NODE_ENV
+```
+
+## Import Maps (Browser)
+
+```html
+<!-- In HTML -->
+<script type="importmap">
+{
+  "imports": {
+    "lodash": "/node_modules/lodash-es/lodash.js",
+    "react": "https://esm.sh/react@18",
+    "utils/": "/src/utils/"
+  }
+}
+</script>
+
+<script type="module">
+import _ from 'lodash';
+import React from 'react';
+import { helper } from 'utils/helper.js';
+</script>
+```
+
+## CommonJS Compatibility
+
+```javascript
+// ESM consuming CommonJS
+import cjsModule from './commonjs-module.cjs';
+import { named } from './commonjs-module.cjs'; // May not work
+
+// Use createRequire for CommonJS in ESM
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const cjsModule = require('./commonjs-module.cjs');
+
+// Access CommonJS metadata in ESM
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+```
+
+## Module Resolution
+
+```javascript
+// Explicit file extensions required in ESM
+import utils from './utils.js'; // Correct
+import utils from './utils';    // Error in ESM
+
+// Directory imports require index.js
+import api from './api/index.js';
+
+// Using import.meta
+console.log(import.meta.url); // file:///path/to/module.js
+console.log(import.meta.resolve('./other.js')); // Resolve relative path
+
+// Detect if module is main
+if (import.meta.url === `file://${process.argv[1]}`) {
+  // This module was run directly
+  main();
+}
+```
+
+## Circular Dependencies
+
+```javascript
+// moduleA.js
+import { b } from './moduleB.js';
+export const a = 'A';
+export function useB() {
+  return b;
+}
+
+// moduleB.js
+import { a } from './moduleA.js';
+export const b = 'B';
+export function useA() {
+  return a; // Works because 'a' is hoisted
+}
+
+// Best practice: avoid circular deps, use dependency injection
+// factory.js
+export function createA(dependencies) {
+  return {
+    name: 'A',
+    useB: () => dependencies.b
+  };
+}
+
+export function createB(dependencies) {
+  return {
+    name: 'B',
+    useA: () => dependencies.a
+  };
+}
+
+// index.js
+const a = createA({});
+const b = createB({});
+a.dependencies = { b };
+b.dependencies = { a };
+```
+
+## Tree Shaking Optimization
+
+```javascript
+// Write side-effect-free code for tree shaking
+// utils.js - Good: pure functions
+export const add = (a, b) => a + b;
+export const multiply = (a, b) => a * b;
+export const divide = (a, b) => a / b;
+
+// Only used functions will be bundled
+import { add } from './utils.js'; // Only 'add' bundled
+
+// Bad: side effects prevent tree shaking
+console.log('Module loaded'); // Side effect
+export const add = (a, b) => a + b;
+
+// Mark as side-effect-free in package.json
+{
+  "sideEffects": false,
+  // OR specify files with side effects
+  "sideEffects": ["*.css", "polyfills.js"]
+}
+```
+
+## Module Patterns
+
+```javascript
+// Singleton pattern
+// database.js
+class Database {
+  #connection = null;
+
+  async connect() {
+    if (!this.#connection) {
+      this.#connection = await createConnection();
+    }
+    return this.#connection;
+  }
+}
+
+export default new Database();
+
+// Factory pattern
+// loggerFactory.js
+export function createLogger(level = 'info') {
+  return {
+    info: (msg) => level !== 'silent' && console.log(msg),
+    error: (msg) => console.error(msg)
+  };
+}
+
+// Facade pattern
+// api.js
+import { get, post, put, del } from './httpClient.js';
+import { auth } from './auth.js';
+import { cache } from './cache.js';
+
+export const api = {
+  async getUser(id) {
+    const cached = cache.get(`user:${id}`);
+    if (cached) return cached;
+
+    const token = await auth.getToken();
+    const user = await get(`/users/${id}`, { token });
+    cache.set(`user:${id}`, user);
+    return user;
+  }
+};
+```
+
+## Node.js ESM Specifics
+
+```javascript
+// package.json
+{
+  "type": "module" // All .js files are ESM
+}
+
+// Use .cjs for CommonJS files when type: "module"
+// Use .mjs for ESM files when type: "commonjs" (default)
+
+// Loading JSON in ESM
+import data from './data.json' assert { type: 'json' };
+
+// OR using fs
+import { readFile } from 'fs/promises';
+const data = JSON.parse(
+  await readFile('./data.json', 'utf-8')
+);
+
+// Top-level await in Node.js ESM
+const config = await fetch('/api/config').then(r => r.json());
+export default config;
+```
+
+## Quick Reference
+
+| Feature | ESM | CommonJS |
+|---------|-----|----------|
+| Syntax | `import`/`export` | `require()`/`module.exports` |
+| Loading | Asynchronous | Synchronous |
+| Tree shaking | Yes | No |
+| Top-level await | Yes | No |
+| Dynamic imports | `await import()` | `require()` |
+| File extension | Required | Optional |
+| `__dirname` | Use `import.meta.url` | Built-in |
+| Browser support | Native | Needs bundler |
+| Default mode | `"type": "module"` | No type field |