@cubis/foundry 0.3.82 → 0.3.84

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/javascript-best-practices/references/async-patterns.md

@@ -1,296 +0,0 @@
-# Async Patterns Reference
-
-## AbortController and AbortSignal
-
-### Basic Cancellation
-
-```javascript
-const controller = new AbortController();
-const { signal } = controller;
-
-// Cancel after 5 seconds
-const timeout = setTimeout(() => controller.abort(), 5_000);
-
-try {
-  const response = await fetch('/api/data', { signal });
-  clearTimeout(timeout);
-  return await response.json();
-} catch (error) {
-  if (error.name === 'AbortError') {
-    console.log('Request was cancelled');
-    return null;
-  }
-  throw error;
-}
-```
-
-### AbortSignal.timeout (ES2024)
-
-```javascript
-// Built-in timeout signal -- no manual AbortController needed
-const response = await fetch('/api/data', {
-  signal: AbortSignal.timeout(5_000),
-});
-```
-
-### AbortSignal.any -- Composing Multiple Signals
-
-```javascript
-// Cancel on either user action OR timeout
-const userController = new AbortController();
-
-const signal = AbortSignal.any([
-  userController.signal,           // User clicks "Cancel"
-  AbortSignal.timeout(30_000),     // 30-second deadline
-]);
-
-try {
-  const data = await fetchLargeDataset('/api/export', { signal });
-} catch (error) {
-  if (error.name === 'AbortError') {
-    // Determine which signal triggered
-    console.log('Operation cancelled or timed out');
-  }
-}
-```
-
-### Propagating Signals Through Call Chains
-
-```javascript
-// Thread the signal through every async operation
-const fetchUserWithPosts = async (userId, { signal } = {}) => {
-  const user = await fetchJson(`/users/${userId}`, { signal });
-
-  // Check signal before starting the next operation
-  signal?.throwIfAborted();
-
-  const posts = await fetchJson(`/users/${userId}/posts`, { signal });
-  return { user, posts };
-};
-```
-
-## Retry with Exponential Backoff
-
-```javascript
-const retry = async (fn, { maxAttempts = 3, baseDelay = 1_000, signal } = {}) => {
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    try {
-      return await fn({ signal });
-    } catch (error) {
-      // Never retry abort errors
-      if (error.name === 'AbortError') throw error;
-
-      // Don't retry on the last attempt
-      if (attempt === maxAttempts) throw error;
-
-      // Exponential backoff with jitter
-      const delay = baseDelay * 2 ** (attempt - 1) + Math.random() * 500;
-      await abortableDelay(delay, signal);
-    }
-  }
-};
-
-// Delay that can be cancelled
-const abortableDelay = (ms, signal) =>
-  new Promise((resolve, reject) => {
-    signal?.throwIfAborted();
-    const timer = setTimeout(resolve, ms);
-    signal?.addEventListener('abort', () => {
-      clearTimeout(timer);
-      reject(signal.reason);
-    }, { once: true });
-  });
-```
-
-## Concurrency Limiting
-
-### Semaphore Pattern
-
-```javascript
-class Semaphore {
-  #permits;
-  #queue = [];
-
-  constructor(permits) {
-    this.#permits = permits;
-  }
-
-  async acquire() {
-    if (this.#permits > 0) {
-      this.#permits--;
-      return;
-    }
-    await new Promise((resolve) => this.#queue.push(resolve));
-  }
-
-  release() {
-    const next = this.#queue.shift();
-    if (next) {
-      next();
-    } else {
-      this.#permits++;
-    }
-  }
-
-  async run(fn) {
-    await this.acquire();
-    try {
-      return await fn();
-    } finally {
-      this.release();
-    }
-  }
-}
-
-// Usage: process 100 URLs with max 5 concurrent requests
-const semaphore = new Semaphore(5);
-const results = await Promise.all(
-  urls.map((url) => semaphore.run(() => fetch(url)))
-);
-```
-
-### Pool Pattern with Results
-
-```javascript
-const pool = async (tasks, concurrency) => {
-  const results = new Array(tasks.length);
-  let index = 0;
-
-  const worker = async () => {
-    while (index < tasks.length) {
-      const i = index++;
-      results[i] = await tasks[i]();
-    }
-  };
-
-  await Promise.all(Array.from({ length: concurrency }, worker));
-  return results;
-};
-```
-
-## Async Generators for Streaming Data
-
-### Paginated API Consumer
-
-```javascript
-async function* fetchAllPages(baseUrl, { signal } = {}) {
-  let cursor = undefined;
-
-  while (true) {
-    signal?.throwIfAborted();
-
-    const url = new URL(baseUrl);
-    if (cursor) url.searchParams.set('cursor', cursor);
-
-    const response = await fetch(url, { signal });
-    if (!response.ok) throw new Error(`HTTP ${response.status}`);
-
-    const page = await response.json();
-    yield* page.items;  // Yield individual items, not pages
-
-    if (!page.nextCursor) break;
-    cursor = page.nextCursor;
-  }
-}
-
-// Consumer processes one item at a time -- constant memory
-for await (const item of fetchAllPages('https://api.example.com/items', { signal })) {
-  await processItem(item);
-}
-```
-
-### Transform Pipeline with Generators
-
-```javascript
-async function* map(source, fn) {
-  for await (const item of source) {
-    yield fn(item);
-  }
-}
-
-async function* filter(source, predicate) {
-  for await (const item of source) {
-    if (predicate(item)) yield item;
-  }
-}
-
-async function* batch(source, size) {
-  let chunk = [];
-  for await (const item of source) {
-    chunk.push(item);
-    if (chunk.length >= size) {
-      yield chunk;
-      chunk = [];
-    }
-  }
-  if (chunk.length > 0) yield chunk;
-}
-
-// Compose a pipeline
-const items = fetchAllPages(url, { signal });
-const active = filter(items, (item) => item.status === 'active');
-const transformed = map(active, (item) => ({ ...item, processedAt: Date.now() }));
-const batches = batch(transformed, 50);
-
-for await (const chunk of batches) {
-  await bulkInsert(chunk);
-}
-```
-
-## Explicit Resource Management (ES2024)
-
-```javascript
-class DatabaseConnection {
-  #connection;
-
-  static async open(url) {
-    const conn = new DatabaseConnection();
-    conn.#connection = await connect(url);
-    return conn;
-  }
-
-  async query(sql, params) {
-    return this.#connection.query(sql, params);
-  }
-
-  // Async dispose -- called automatically by `await using`
-  async [Symbol.asyncDispose]() {
-    await this.#connection.close();
-  }
-}
-
-// Connection is automatically closed when scope exits
-async function getUser(id) {
-  await using db = await DatabaseConnection.open(DATABASE_URL);
-  return db.query('SELECT * FROM users WHERE id = $1', [id]);
-  // db[Symbol.asyncDispose]() called automatically here
-}
-```
-
-## Promise Combinator Selection Guide
-
-| Combinator | Behavior | Use When |
-| --- | --- | --- |
-| `Promise.all(ps)` | Resolves when ALL resolve; rejects on FIRST rejection | All results needed, fail-fast on any error |
-| `Promise.allSettled(ps)` | Resolves when ALL settle (resolve or reject) | Need all outcomes, partial failure acceptable |
-| `Promise.race(ps)` | Settles with FIRST settled promise | Timeout racing, cache vs network |
-| `Promise.any(ps)` | Resolves with FIRST fulfilled; rejects if ALL reject | Redundant sources, fastest mirror |
-
-## Event Loop Yielding for Long Tasks
-
-```javascript
-// Yield to the event loop in CPU-intensive loops
-const processLargeArray = async (items, batchSize = 1_000) => {
-  const results = [];
-  for (let i = 0; i < items.length; i += batchSize) {
-    const batch = items.slice(i, i + batchSize);
-    results.push(...batch.map(transform));
-
-    // Yield to prevent blocking the event loop
-    if (i + batchSize < items.length) {
-      await scheduler?.yield?.() ?? new Promise((r) => setTimeout(r, 0));
-    }
-  }
-  return results;
-};
-```

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/javascript-best-practices/references/modules-bundling.md

@@ -1,202 +0,0 @@
-# Modules & Bundling Reference
-
-## ESM vs CJS: Choosing the Right Format
-
-### ESM (ECMAScript Modules) -- Default for New Code
-
-ESM is the language-standard module system. It provides static analysis, tree-shaking, and top-level `await`.
-
-```javascript
-// Named exports -- preferred for tree-shaking
-export const add = (a, b) => a + b;
-export const subtract = (a, b) => a - b;
-
-// Default export -- use sparingly, one per module
-export default class Calculator { /* ... */ }
-
-// Re-export for public API surfaces
-export { add, subtract } from './math.js';
-
-// Namespace import -- when you need the whole module
-import * as math from './math.js';
-```
-
-### CJS (CommonJS) -- Legacy and Server-Only
-
-CJS is synchronous and dynamic. It cannot be tree-shaken by bundlers.
-
-```javascript
-// CJS is still used in: Node.js config files (jest.config.js),
-// older libraries, and tools that don't support ESM yet.
-const { readFile } = require('node:fs/promises');
-module.exports = { myFunction };
-```
-
-### package.json Configuration for ESM
-
-```json
-{
-  "type": "module",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
-    },
-    "./utils": {
-      "import": "./dist/utils.js",
-      "require": "./dist/utils.cjs"
-    }
-  },
-  "files": ["dist"],
-  "sideEffects": false
-}
-```
-
-Key fields:
-- **`"type": "module"`** -- `.js` files are ESM; use `.cjs` for CommonJS files.
-- **`"exports"`** -- Controls what consumers can import. Replaces `"main"` and `"module"`.
-- **`"sideEffects": false`** -- Tells bundlers every module is safe to tree-shake.
-- **Condition order matters**: `"types"` before `"default"` in each condition block.
-
-### __dirname / __filename Replacement in ESM
-
-```javascript
-// CJS had __dirname and __filename as globals
-// ESM uses import.meta.url instead
-
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// Read a file relative to this module
-const configPath = join(__dirname, '../config.json');
-```
-
-## Bundling Strategies
-
-### Vite (Browser and SSR)
-
-```javascript
-// vite.config.js
-import { defineConfig } from 'vite';
-
-export default defineConfig({
-  build: {
-    target: 'es2024',
-    rollupOptions: {
-      output: {
-        manualChunks: {
-          vendor: ['react', 'react-dom'],
-        },
-      },
-    },
-  },
-});
-```
-
-### esbuild (Server and CLI)
-
-```javascript
-// build.mjs
-import { build } from 'esbuild';
-
-await build({
-  entryPoints: ['src/index.js'],
-  bundle: true,
-  platform: 'node',
-  target: 'node22',
-  format: 'esm',
-  outfile: 'dist/index.js',
-  external: ['node:*'],  // Don't bundle Node built-ins
-  sourcemap: true,
-});
-```
-
-### tsup (Library Dual-Format)
-
-```javascript
-// tsup.config.js
-import { defineConfig } from 'tsup';
-
-export default defineConfig({
-  entry: ['src/index.ts'],
-  format: ['esm', 'cjs'],
-  dts: true,
-  clean: true,
-  splitting: false,  // Single-file output for libraries
-  sourcemap: true,
-});
-```
-
-## Tree-Shaking and Barrel Files
-
-Barrel files (`index.js` that re-exports everything) are the most common tree-shaking blocker.
-
-```javascript
-// BAD: barrel re-exports everything
-// consumers/index.js
-export * from './userService.js';
-export * from './orderService.js';
-export * from './analyticsService.js';
-// Importing { userService } still pulls in orderService and analyticsService
-// if the bundler cannot prove they are side-effect-free.
-
-// GOOD: explicit exports
-// consumers/index.js
-export { UserService } from './userService.js';
-export { OrderService } from './orderService.js';
-// Only export what the public API needs
-```
-
-### Verifying Tree-Shaking
-
-```bash
-# Check bundle contents with esbuild
-esbuild src/index.js --bundle --analyze | grep "output size"
-
-# Visualize with rollup-plugin-visualizer (Vite)
-npx vite-bundle-visualizer
-```
-
-## Dynamic Import for Code-Splitting
-
-```javascript
-// Lazy-load heavy modules only when needed
-const processImage = async (buffer) => {
-  const { default: sharp } = await import('sharp');
-  return sharp(buffer).resize(800, 600).webp().toBuffer();
-};
-
-// Conditional loading based on environment
-const logger = await import(
-  process.env.NODE_ENV === 'production'
-    ? './logger-prod.js'
-    : './logger-dev.js'
-);
-```
-
-## Import Maps (Browser-Native)
-
-```html
-<!-- No bundler needed for modern browsers -->
-<script type="importmap">
-{
-  "imports": {
-    "lodash-es": "https://cdn.skypack.dev/lodash-es",
-    "@/": "./src/"
-  }
-}
-</script>
-<script type="module">
-import { debounce } from 'lodash-es';
-import { App } from '@/app.js';
-</script>
-```