设计tracer

.trae/rules/project_rules.md

@@ -0,0 +1,15 @@
+我正在设计一个数据结构与算法可视化平台，在我的设想中，平台会提供一个代码编辑器，用户可以在其中编写算法的实现代码，当用户点击运行按钮时，平台会调用后端的编译器来执行用户编写的代码，获取到算法执行过程中所涉及的数据结构的变化，并将整个过程可视化地展示在平台中。
+
+从技术的角度，我希望它能够适配不同的编程语言，所以我不会考虑从编译技术的层面去适配不同的编程语言(例如自定义一个编译器)，而是考虑设计一套多语言的 SDK 来实现这一目标。从整体上来看，SDK 提供的 API 用于“标记”数据结构的操作，用户可以在算法的实现中调用这些 API 来标记数据结构的变化，这样在代码被编译运行后，就能够获取数据结构的变化过程(序列化为 JSON)。
+
+这样如果从用户的角度来看，用户可以几乎不修改算法的实现，而是只需要在合适的位置调用平台提供的 API 即可。
+
+这个项目是关于这个平台的多语言 SDK 设计与实现方案。
+
+项目中有这样一些概念：
+
+- Tracer: 用于记录数据结构的变化过程，每一种数据结构都有一个对应的 Tracer 类(ArrayTracer, StackTracer, QueueTracer, MatrixTracer, SortTracer, LinkTracer, TreeTracer, GraphTracer)。
+
+- Action: 用于描述数据结构的操作类型，每一种操作都有一个对应的 Action。
+
+- Command: 用于描述每一次数据结构操作的指令，一条指令包含了 tracer、action、params，并最终会序列化为 JSON。

bun.lock

@@ -1,29 +0,0 @@
-{
-  "lockfileVersion": 1,
-  "workspaces": {
-    "": {
-      "name": "structrail-design",
-      "devDependencies": {
-        "@types/bun": "latest",
-      },
-      "peerDependencies": {
-        "typescript": "^5",
-      },
-    },
-  },
-  "packages": {
-    "@types/bun": ["@types/bun@1.2.23", "", { "dependencies": { "bun-types": "1.2.23" } }, "sha512-le8ueOY5b6VKYf19xT3McVbXqLqmxzPXHsQT/q9JHgikJ2X22wyTW3g3ohz2ZMnp7dod6aduIiq8A14Xyimm0A=="],
-
-    "@types/node": ["@types/node@24.7.1", "", { "dependencies": { "undici-types": "~7.14.0" } }, "sha512-CmyhGZanP88uuC5GpWU9q+fI61j2SkhO3UGMUdfYRE6Bcy0ccyzn1Rqj9YAB/ZY4kOXmNf0ocah5GtphmLMP6Q=="],
-
-    "@types/react": ["@types/react@19.2.2", "", { "dependencies": { "csstype": "^3.0.2" } }, "sha512-6mDvHUFSjyT2B2yeNx2nUgMxh9LtOWvkhIU3uePn2I2oyNymUAX1NIsdgviM4CH+JSrp2D2hsMvJOkxY+0wNRA=="],
-
-    "bun-types": ["bun-types@1.2.23", "", { "dependencies": { "@types/node": "*" }, "peerDependencies": { "@types/react": "^19" } }, "sha512-R9f0hKAZXgFU3mlrA0YpE/fiDvwV0FT9rORApt2aQVWSuJDzZOyB5QLc0N/4HF57CS8IXJ6+L5E4W1bW6NS2Aw=="],
-
-    "csstype": ["csstype@3.1.3", "", {}, "sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw=="],
-
-    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
-
-    "undici-types": ["undici-types@7.14.0", "", {}, "sha512-QQiYxHuyZ9gQUIrmPo3IA+hUl4KYk8uSA7cHrcKd/l3p1OTpZcM0Tbp9x7FAtXdAYhlasd60ncPpgu6ihG6TOA=="],
-  }
-}

index.ts

@@ -1,7 +0,0 @@
-import { ArrayTracer } from "./src/tracers.ts";
-
-const arrayTracer = ArrayTracer.define<number>({
-  description: "Array Tracer",
-});
-
-arrayTracer.preset([1, 2, 3]);

tracers.ts/README.md

@@ -1,4 +1,4 @@
-# structrail-design
+# tracers.ts
 
 To install dependencies:
 

tracers.ts/bun.lock

@@ -0,0 +1,29 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "tracers.ts",
+      "devDependencies": {
+        "@types/bun": "latest",
+      },
+      "peerDependencies": {
+        "typescript": "^5",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.2", "", { "dependencies": { "bun-types": "1.3.2" } }, "sha512-t15P7k5UIgHKkxwnMNkJbWlh/617rkDGEdSsDbu+qNHTaz9SKf7aC8fiIlUdD5RPpH6GEkP0cK7WlvmrEBRtWg=="],
+
+    "@types/node": ["@types/node@24.10.1", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-GNWcUTRBgIRJD5zj+Tq0fKOJ5XZajIiBroOF0yvj2bSU1WvNdYS/dn9UxwsujGW4JX06dnHyjV2y9rRaybH0iQ=="],
+
+    "@types/react": ["@types/react@19.2.4", "", { "dependencies": { "csstype": "^3.0.2" } }, "sha512-tBFxBp9Nfyy5rsmefN+WXc1JeW/j2BpBHFdLZbEVfs9wn3E3NRFxwV0pJg8M1qQAexFpvz73hJXFofV0ZAu92A=="],
+
+    "bun-types": ["bun-types@1.3.2", "", { "dependencies": { "@types/node": "*" }, "peerDependencies": { "@types/react": "^19" } }, "sha512-i/Gln4tbzKNuxP70OWhJRZz1MRfvqExowP7U6JKoI8cntFrtxg7RJK3jvz7wQW54UuvNC8tbKHHri5fy74FVqg=="],
+
+    "csstype": ["csstype@3.1.3", "", {}, "sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+  }
+}

tracers.ts/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "structrail-design",
+  "name": "tracers.ts",
   "module": "index.ts",
   "type": "module",
   "private": true,

tracers.ts/src/commander/index.ts

@@ -0,0 +1,26 @@
+import type { TracerCommand } from '../types/command';
+
+export class Commander {
+  private commands: TracerCommand<unknown>[];
+
+  private constructor() {
+    this.commands = [];
+  }
+
+  private static instance: Commander | null = null;
+
+  public static getInstance(): Commander {
+    if (!this.instance) {
+      this.instance = new Commander();
+    }
+    return this.instance;
+  }
+
+  public command<T = never>(command: TracerCommand<T>) {
+    this.commands.push(command);
+  }
+
+  public output() {
+    return JSON.stringify(this.commands);
+  }
+}

tracers.ts/src/index.ts

@@ -0,0 +1,10 @@
+import { Commander } from './commander';
+import { ArrayTracer } from './tracer';
+
+const arrayTracer = ArrayTracer.define<number>({ description: 'Array Tracer' });
+
+arrayTracer.preset([1, 2, 3]);
+
+const commander = Commander.getInstance();
+const commands = commander.output();
+console.log(commands);

tracers.ts/src/registry/index.ts

@@ -0,0 +1,25 @@
+import type { TracerType } from "../types/tracer";
+
+export class Registry {
+  private tracers: Map<TracerType, string[]>;
+
+  private constructor() {
+    this.tracers = new Map<TracerType, string[]>();
+  }
+
+  private static instance: Registry | null = null;
+
+  public static getInstance() {
+    if (!this.instance) {
+      this.instance = new Registry();
+    }
+    return this.instance;
+  }
+
+  public register(tracerType: TracerType, string: string) {
+    if (!this.tracers.has(tracerType)) {
+      this.tracers.set(tracerType, []);
+    }
+    this.tracers.get(tracerType)?.push(string);
+  }
+}

tracers.ts/src/tracer/array-tracer.ts

@@ -0,0 +1,94 @@
+import { Commander } from '../commander';
+import { Registry } from '../registry';
+
+export interface ArrayTracerOption<T> {
+  description: string;
+}
+
+export class ArrayTracer<T> {
+  private tracerId: string;
+
+  private constructor() {
+    this.tracerId = crypto.randomUUID();
+  }
+
+  public static define<T>(option: ArrayTracerOption<T>): ArrayTracer<T> {
+    const arrayTracer = new ArrayTracer();
+    const registry = Registry.getInstance();
+    registry.register('ArrayTracer', arrayTracer.tracerId);
+    const commander = Commander.getInstance();
+    commander.command({
+      action: 'define',
+      tracer: null,
+      payload: {
+        type: 'ArrayTracer',
+        id: arrayTracer.tracerId,
+        desc: option.description,
+      },
+    });
+    return arrayTracer;
+  }
+
+  public preset(array: T[]) {
+    const commander = Commander.getInstance();
+    commander.command({
+      action: 'preset',
+      tracer: this.tracerId,
+      payload: array,
+    });
+  }
+
+  public extend(size: number) {
+    const commander = Commander.getInstance();
+    commander.command({
+      action: 'extend',
+      tracer: this.tracerId,
+      payload: { size },
+    });
+  }
+
+  public shrink(size: number) {
+    const commander = Commander.getInstance();
+    commander.command({
+      action: 'shrink',
+      tracer: this.tracerId,
+      payload: { size },
+    });
+  }
+
+  public pick(index: number) {
+    const commander = Commander.getInstance();
+    commander.command({
+      action: 'pick',
+      tracer: this.tracerId,
+      payload: { index },
+    });
+  }
+
+  public drop(index: number) {
+    const commander = Commander.getInstance();
+    commander.command({
+      action: 'drop',
+      tracer: this.tracerId,
+      payload: { index },
+    });
+  }
+
+  public patch(index: number, value: T) {
+    const commander = Commander.getInstance();
+    commander.command({
+      action: 'patch',
+      tracer: this.tracerId,
+      payload: { index, value },
+    });
+  }
+
+  public reset(index: number) {
+    const commander = Commander.getInstance();
+    commander.command({
+      action: 'reset',
+      tracer: this.tracerId,
+      payload: { index },
+    });
+  }
+}

tracers.ts/src/tracer/index.ts

@@ -0,0 +1 @@
+export * from "./array-tracer";

tracers.ts/src/types/action/index.ts

@@ -0,0 +1,5 @@
+import type { ArrayTracerCommand } from '../command';
+
+export type ArrayTracerAction = ArrayTracerCommand['action'];
+
+export type TracerAction = ArrayTracerAction;

tracers.ts/src/types/command/array-tracer-command.ts

@@ -0,0 +1,57 @@
+export type ArrayTracerDefineCommand = {
+  action: 'define';
+  tracer: null;
+  payload: { type: 'ArrayTracer'; id: string; desc?: string };
+};
+
+export type ArrayTracerPresetCommand<T = unknown> = {
+  action: 'preset';
+  tracer: string;
+  payload: T[];
+};
+
+export type ArrayTracerExtendCommand = {
+  action: 'extend';
+  tracer: string;
+  payload: { size: number };
+};
+
+export type ArrayTracerShrinkCommand = {
+  action: 'shrink';
+  tracer: string;
+  payload: { size: number };
+};
+
+export type ArrayTracerPickCommand = {
+  action: 'pick';
+  tracer: string;
+  payload: { index: number };
+};
+
+export type ArrayTracerDropCommand = {
+  action: 'drop';
+  tracer: string;
+  payload: { index: number };
+};
+
+export type ArrayTracerPatchCommand<T = unknown> = {
+  action: 'patch';
+  tracer: string;
+  payload: { index: number; value: T };
+};
+
+export type ArrayTracerResetCommand = {
+  action: 'reset';
+  tracer: string;
+  payload: { index: number };
+};
+
+export type ArrayTracerCommand<T = never> =
+  | ArrayTracerDefineCommand
+  | ArrayTracerPresetCommand<T>
+  | ArrayTracerExtendCommand
+  | ArrayTracerShrinkCommand
+  | ArrayTracerPickCommand
+  | ArrayTracerDropCommand
+  | ArrayTracerPatchCommand<T>
+  | ArrayTracerResetCommand;

tracers.ts/src/types/command/index.ts

@@ -0,0 +1,5 @@
+import type { ArrayTracerCommand } from './array-tracer-command';
+
+export * from './array-tracer-command';
+
+export type TracerCommand<T = never> = ArrayTracerCommand<T>;

tracers.ts/src/types/tracer/index.ts

@@ -0,0 +1,5 @@
+import type { ArrayTracerDefineCommand } from '../command';
+
+type ArrayTracer = ArrayTracerDefineCommand['payload']['type'];
+
+export type TracerType = ArrayTracer;