merge docs/generator-slot

Author: cieplypolar

.github/workflows/ci.yml

@@ -10,41 +10,6 @@ on:
       - checks_requested
 
 jobs:
-  check-circular-deps:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          run_install: false
-
-      - name: Use Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22.x
-          cache: 'pnpm'
-
-      - name: Install dpdm
-        run: pnpm install -g dpdm
-
-      - name: Check circular dependencies
-        run: dpdm --exit-code circular:1 packages/**/index.ts -T
-
-  lint-and-format:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: biomejs/setup-biome@v2
-      - uses: denoland/setup-deno@v2
-        with:
-          deno-version: v2.x # Run with latest stable Deno.
-      - name: Lint
-        run: biome ci --formatter-enabled=false --organize-imports-enabled=false .
-      - name: Check formatting
-        run: deno fmt --check
-
   build-and-test:
     runs-on: ubuntu-latest
     steps:

.github/workflows/treeshake-test.yml

@@ -0,0 +1,128 @@
+name: Tree-shake test
+
+on:
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      target_branch:
+        description: 'Target branch to compare against'
+        required: true
+        default: 'main'
+
+jobs:
+  treeshake-test:
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.27.0
+          run_install: false
+
+      - name: Checkout PR branch
+        uses: actions/checkout@v4
+        with:
+          path: pr-branch
+
+      - name: Checkout target branch
+        uses: actions/checkout@v4
+        with:
+          path: target-branch
+          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.target_branch || github.base_ref }}
+
+      - name: Install dependencies (PR branch)
+        working-directory: pr-branch
+        run: pnpm install
+
+      - name: Install dependencies (target branch)
+        working-directory: target-branch
+        run: pnpm install
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          cache: 'pnpm'
+          cache-dependency-path: |
+            pr-branch/pnpm-lock.yaml
+            target-branch/pnpm-lock.yaml
+
+      - name: Generate import tests on PR branch
+        working-directory: pr-branch
+        run: pnpm --filter treeshake-test generate-tests
+
+      - name: Generate import tests on target branch
+        working-directory: target-branch
+        run: pnpm --filter treeshake-test generate-tests
+
+      - name: Run tree-shake test on PR branch
+        working-directory: pr-branch
+        run: pnpm --filter treeshake-test test --tsdown ${{ github.event_name == 'workflow_dispatch' && '--webpack' || '' }}
+
+      - name: Run tree-shake test on target branch
+        working-directory: target-branch
+        run: pnpm --filter treeshake-test test --tsdown ${{ github.event_name == 'workflow_dispatch' && '--webpack' || '' }}
+
+      - name: Compare results
+        run: |
+          node pr-branch/apps/treeshake-test/compareResults.ts \
+            pr-branch/apps/treeshake-test/results.json \
+            target-branch/apps/treeshake-test/results.json \
+            > comparison.md
+
+      - name: Comment PR with results
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const comparison = fs.readFileSync('comparison.md', 'utf8');
+
+            const botCommentIdentifier = '<!-- treeshake-test-bot-comment -->';
+
+            async function findBotComment(issueNumber) {
+              if (!issueNumber) return null;
+              const comments = await github.rest.issues.listComments({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: issueNumber,
+              });
+              return comments.data.find((comment) =>
+                comment.body.includes(botCommentIdentifier)
+              );
+            }
+
+            async function createOrUpdateComment(issueNumber) {
+              if (!issueNumber) {
+                console.log('No issue number provided. Cannot post or update comment.');
+                return;
+              }
+
+              const existingComment = await findBotComment(issueNumber);
+              if (existingComment) {
+                await github.rest.issues.updateComment({
+                  ...context.repo,
+                  comment_id: existingComment.id,
+                  body: botCommentIdentifier + '\n' + comparison,
+                });
+              } else {
+                await github.rest.issues.createComment({
+                  ...context.repo,
+                  issue_number: issueNumber,
+                  body: botCommentIdentifier + '\n' + comparison,
+                });
+              }
+            }
+
+            const issueNumber = context.issue.number;
+            if (!issueNumber) {
+              console.log('No issue number found in context. Skipping comment.');
+            } else {
+              await createOrUpdateComment(issueNumber);
+            }
+            await core.summary
+              .addRaw(comparison)
+              .write();

README.md

@@ -8,11 +8,41 @@
 
 </div>
 
-**TypeGPU** is a TypeScript library that enhances the WebGPU API, allowing
-resource management in a type-safe, declarative way.
+**TypeGPU** is a modular and open-ended toolkit for WebGPU, with advanced type
+inference and the ability to write shaders in TypeScript.
+
+```ts
+const neighborhood = (a: number, r: number) => {
+  'use gpu';
+  return d.vec2f(a - r, a + r);
+};
+
+//
+// #1) Can be called in JS
+//
+const range = neighborhood(1.1, 0.5);
+//    ^? d.v2f
+
+//
+// #2) Used to generate WGSL
+//
+const main = () => {
+  'use gpu';
+  return neighborhood(1.1, 0.5);
+};
+
+const wgsl = tgpu.resolve([main]);
+//    ^? string
+
+//
+// #3) Executed on the GPU (generates WGSL underneath)
+//
+root['~unstable']
+  .createGuardedComputePipeline(main)
+  .dispatchThreads();
+```
 
 <div align="center">
-<video width="512" autoplay muted loop playsinline src="https://github.com/user-attachments/assets/5bca716d-477d-44a1-a839-5df0c8d9044c"></video>
 
 <!-- automd:badges color="plum" license name="typegpu" bundlephobia no-npmDownloads -->
 

apps/bun-example/index.ts

@@ -10,8 +10,6 @@ const createRandomBoid = tgpu.fn([], Boid)(() => {
   return { pos: randf.inUnitCube() };
 });
 
-const shaderCode = tgpu.resolve({
-  externals: { createRandomBoid },
-});
+const shaderCode = tgpu.resolve([createRandomBoid]);
 
 console.log(shaderCode);

apps/treeshake-test/.gitignore

@@ -0,0 +1,5 @@
+dist/
+
+results.md
+results.json
+tests/*_from_*

apps/treeshake-test/bundleWith.ts

@@ -0,0 +1,119 @@
+import { build as esbuild } from 'esbuild';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { build as tsdown } from 'tsdown';
+import esbuildPlugin from 'unplugin-typegpu/esbuild';
+import rolldownPlugin from 'unplugin-typegpu/rolldown';
+import webpackPlugin from 'unplugin-typegpu/webpack';
+import webpack from 'webpack';
+
+export type ResultRecord = {
+  testFilename: string;
+  bundler: string;
+  size: number;
+};
+
+export async function bundleWithEsbuild(
+  entryUrl: URL,
+  outDir: URL,
+): Promise<URL> {
+  const entryFileName = path.basename(entryUrl.pathname, '.ts');
+  const outPath = new URL(`${entryFileName}.esbuild.js`, outDir);
+  await esbuild({
+    plugins: [esbuildPlugin({})],
+    entryPoints: [entryUrl.pathname],
+    bundle: true,
+    outfile: outPath.pathname,
+    format: 'esm',
+    minify: true,
+    treeShaking: true,
+  });
+  return outPath;
+}
+
+export async function bundleWithWebpack(
+  entryPath: URL,
+  outDir: URL,
+): Promise<URL> {
+  const entryFileName = path.basename(entryPath.pathname, '.ts');
+  const outPath = new URL(`./${entryFileName}.webpack.js`, outDir);
+
+  return new Promise((resolve, reject) => {
+    webpack(
+      {
+        entry: entryPath.pathname,
+        output: {
+          path: path.dirname(outPath.pathname),
+          filename: path.basename(outPath.pathname),
+        },
+        plugins: [webpackPlugin({})],
+        module: {
+          rules: [
+            {
+              test: /\.ts$/,
+              use: {
+                loader: 'ts-loader',
+                options: {
+                  compilerOptions: {
+                    module: 'es2015',
+                    target: 'es2015',
+                    esModuleInterop: true,
+                    allowSyntheticDefaultImports: true,
+                    skipLibCheck: true,
+                  },
+                  transpileOnly: true,
+                },
+              },
+              exclude: /node_modules/,
+            },
+          ],
+        },
+        optimization: {
+          minimize: true,
+        },
+      },
+      (err, stats) => {
+        if (err || stats?.hasErrors()) {
+          console.error(stats?.toString());
+          reject(err || new Error('Webpack bundling failed'));
+        } else {
+          resolve(outPath);
+        }
+      },
+    );
+  });
+}
+
+export async function bundleWithTsdown(
+  entryUrl: URL,
+  outDir: URL,
+): Promise<URL> {
+  const entryFileName = path.basename(entryUrl.pathname, '.ts');
+  const outPath = new URL(`./${entryFileName}.tsdown.js`, outDir);
+
+  try {
+    await tsdown({
+      plugins: [rolldownPlugin({})],
+      outputOptions: {
+        name: path.basename(outPath.pathname),
+        dir: path.dirname(outPath.pathname),
+      },
+      minify: true,
+      platform: 'neutral',
+      clean: false,
+      entry: {
+        [`${entryFileName}.tsdown`]: entryUrl.pathname,
+      },
+      noExternal: /.*/,
+    });
+
+    return outPath;
+  } catch (error) {
+    throw new Error(`tsdown bundling failed`, { cause: error });
+  }
+}
+
+export async function getFileSize(filePath: URL): Promise<number> {
+  const stats = await fs.stat(filePath);
+  return stats.size;
+}