npm - kicadts - Versions diffs - 0.0.1 - Mend

kicadts 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (188) hide show

package/.cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc +111 -0
package/.vscode/settings.json +16 -0
package/AGENTS.md +30 -0
package/README.md +206 -0
package/biome.json +93 -0
package/bun.lock +48 -0
package/bunfig.toml +5 -0
package/lib/index.ts +1 -0
package/lib/sexpr/base-classes/SxClass.ts +164 -0
package/lib/sexpr/base-classes/SxPrimitiveBoolean.ts +35 -0
package/lib/sexpr/base-classes/SxPrimitiveNumber.ts +26 -0
package/lib/sexpr/base-classes/SxPrimitiveString.ts +26 -0
package/lib/sexpr/classes/At.ts +38 -0
package/lib/sexpr/classes/Bus.ts +83 -0
package/lib/sexpr/classes/BusEntry.ts +142 -0
package/lib/sexpr/classes/Color.ts +29 -0
package/lib/sexpr/classes/Dnp.ts +8 -0
package/lib/sexpr/classes/EmbeddedFonts.ts +70 -0
package/lib/sexpr/classes/ExcludeFromSim.ts +8 -0
package/lib/sexpr/classes/FieldsAutoplaced.ts +8 -0
package/lib/sexpr/classes/Footprint.ts +719 -0
package/lib/sexpr/classes/FootprintAttr.ts +102 -0
package/lib/sexpr/classes/FootprintAutoplaceCost180.ts +9 -0
package/lib/sexpr/classes/FootprintAutoplaceCost90.ts +9 -0
package/lib/sexpr/classes/FootprintClearance.ts +9 -0
package/lib/sexpr/classes/FootprintDescr.ts +44 -0
package/lib/sexpr/classes/FootprintLocked.ts +32 -0
package/lib/sexpr/classes/FootprintModel.ts +145 -0
package/lib/sexpr/classes/FootprintNetTiePadGroups.ts +50 -0
package/lib/sexpr/classes/FootprintPad.ts +705 -0
package/lib/sexpr/classes/FootprintPath.ts +44 -0
package/lib/sexpr/classes/FootprintPlaced.ts +32 -0
package/lib/sexpr/classes/FootprintPrivateLayers.ts +56 -0
package/lib/sexpr/classes/FootprintSheetfile.ts +44 -0
package/lib/sexpr/classes/FootprintSheetname.ts +44 -0
package/lib/sexpr/classes/FootprintSolderMaskMargin.ts +9 -0
package/lib/sexpr/classes/FootprintSolderPasteMargin.ts +9 -0
package/lib/sexpr/classes/FootprintSolderPasteRatio.ts +9 -0
package/lib/sexpr/classes/FootprintTags.ts +44 -0
package/lib/sexpr/classes/FootprintTedit.ts +21 -0
package/lib/sexpr/classes/FootprintThermalGap.ts +9 -0
package/lib/sexpr/classes/FootprintThermalWidth.ts +9 -0
package/lib/sexpr/classes/FootprintZoneConnect.ts +9 -0
package/lib/sexpr/classes/FpArc.ts +289 -0
package/lib/sexpr/classes/FpCircle.ts +293 -0
package/lib/sexpr/classes/FpLine.ts +288 -0
package/lib/sexpr/classes/FpPoly.ts +266 -0
package/lib/sexpr/classes/FpPolyFill.ts +48 -0
package/lib/sexpr/classes/FpPolyLocked.ts +40 -0
package/lib/sexpr/classes/FpRect.ts +293 -0
package/lib/sexpr/classes/FpText.ts +341 -0
package/lib/sexpr/classes/FpTextBox.ts +412 -0
package/lib/sexpr/classes/GrLine.ts +245 -0
package/lib/sexpr/classes/GrLineAngle.ts +32 -0
package/lib/sexpr/classes/GrLineEnd.ts +61 -0
package/lib/sexpr/classes/GrLineLocked.ts +40 -0
package/lib/sexpr/classes/GrLineStart.ts +61 -0
package/lib/sexpr/classes/GrText.ts +202 -0
package/lib/sexpr/classes/Image.ts +256 -0
package/lib/sexpr/classes/InBom.ts +8 -0
package/lib/sexpr/classes/Junction.ts +134 -0
package/lib/sexpr/classes/KicadPcb.ts +313 -0
package/lib/sexpr/classes/KicadSch.ts +303 -0
package/lib/sexpr/classes/KicadSchGenerator.ts +32 -0
package/lib/sexpr/classes/KicadSchGeneratorVersion.ts +30 -0
package/lib/sexpr/classes/KicadSchVersion.ts +22 -0
package/lib/sexpr/classes/Label.ts +136 -0
package/lib/sexpr/classes/Layer.ts +51 -0
package/lib/sexpr/classes/Layers.ts +47 -0
package/lib/sexpr/classes/LibSymbols.ts +61 -0
package/lib/sexpr/classes/NoConnect.ts +73 -0
package/lib/sexpr/classes/OnBoard.ts +8 -0
package/lib/sexpr/classes/PadChamfer.ts +50 -0
package/lib/sexpr/classes/PadChamferRatio.ts +9 -0
package/lib/sexpr/classes/PadClearance.ts +9 -0
package/lib/sexpr/classes/PadDieLength.ts +9 -0
package/lib/sexpr/classes/PadDrill.ts +145 -0
package/lib/sexpr/classes/PadDrillOffset.ts +54 -0
package/lib/sexpr/classes/PadLayers.ts +59 -0
package/lib/sexpr/classes/PadNet.ts +56 -0
package/lib/sexpr/classes/PadOptions.ts +182 -0
package/lib/sexpr/classes/PadPinFunction.ts +9 -0
package/lib/sexpr/classes/PadPinType.ts +9 -0
package/lib/sexpr/classes/PadPrimitiveGrArc.ts +254 -0
package/lib/sexpr/classes/PadPrimitiveGrCircle.ts +279 -0
package/lib/sexpr/classes/PadPrimitiveGrLine.ts +126 -0
package/lib/sexpr/classes/PadPrimitives.ts +289 -0
package/lib/sexpr/classes/PadRectDelta.ts +57 -0
package/lib/sexpr/classes/PadRoundrectRratio.ts +9 -0
package/lib/sexpr/classes/PadSize.ts +54 -0
package/lib/sexpr/classes/PadSolderMaskMargin.ts +9 -0
package/lib/sexpr/classes/PadSolderPasteMargin.ts +9 -0
package/lib/sexpr/classes/PadSolderPasteMarginRatio.ts +9 -0
package/lib/sexpr/classes/PadTeardrops.ts +208 -0
package/lib/sexpr/classes/PadThermalBridgeAngle.ts +9 -0
package/lib/sexpr/classes/PadThermalGap.ts +9 -0
package/lib/sexpr/classes/PadThermalWidth.ts +9 -0
package/lib/sexpr/classes/PadZoneConnect.ts +9 -0
package/lib/sexpr/classes/Paper.ts +119 -0
package/lib/sexpr/classes/PcbGeneral.ts +75 -0
package/lib/sexpr/classes/PcbGeneralLegacyTeardrops.ts +44 -0
package/lib/sexpr/classes/PcbGeneralThickness.ts +9 -0
package/lib/sexpr/classes/PcbGenerator.ts +16 -0
package/lib/sexpr/classes/PcbGeneratorVersion.ts +16 -0
package/lib/sexpr/classes/PcbLayerDefinition.ts +102 -0
package/lib/sexpr/classes/PcbLayers.ts +34 -0
package/lib/sexpr/classes/PcbNet.ts +56 -0
package/lib/sexpr/classes/PcbVersion.ts +9 -0
package/lib/sexpr/classes/Property.ts +246 -0
package/lib/sexpr/classes/PropertyHide.ts +9 -0
package/lib/sexpr/classes/PropertyUnlocked.ts +9 -0
package/lib/sexpr/classes/Pts.ts +65 -0
package/lib/sexpr/classes/RenderCache.ts +221 -0
package/lib/sexpr/classes/SchematicText.ts +141 -0
package/lib/sexpr/classes/Segment.ts +222 -0
package/lib/sexpr/classes/SegmentEnd.ts +59 -0
package/lib/sexpr/classes/SegmentLocked.ts +33 -0
package/lib/sexpr/classes/SegmentNet.ts +62 -0
package/lib/sexpr/classes/SegmentStart.ts +59 -0
package/lib/sexpr/classes/Setup/PcbPlotParams.ts +729 -0
package/lib/sexpr/classes/Setup/PcbPlotParamsBase.ts +9 -0
package/lib/sexpr/classes/Setup/PcbPlotParamsNumericProperties.ts +105 -0
package/lib/sexpr/classes/Setup/PcbPlotParamsStringPropertiesA.ts +104 -0
package/lib/sexpr/classes/Setup/PcbPlotParamsStringPropertiesB.ts +105 -0
package/lib/sexpr/classes/Setup/Setup.ts +573 -0
package/lib/sexpr/classes/Setup/SetupPropertyTypes.ts +119 -0
package/lib/sexpr/classes/Setup/Stackup.ts +140 -0
package/lib/sexpr/classes/Setup/StackupLayer.ts +233 -0
package/lib/sexpr/classes/Setup/StackupLayerProperties.ts +78 -0
package/lib/sexpr/classes/Setup/StackupProperties.ts +41 -0
package/lib/sexpr/classes/Setup/base.ts +167 -0
package/lib/sexpr/classes/Setup/index.ts +14 -0
package/lib/sexpr/classes/Setup/setupMultiValueProperties.ts +54 -0
package/lib/sexpr/classes/Setup/setupNumericProperties.ts +151 -0
package/lib/sexpr/classes/Setup/setupPropertyHandlers.ts +90 -0
package/lib/sexpr/classes/Setup/setupStringProperties.ts +75 -0
package/lib/sexpr/classes/Sheet.ts +205 -0
package/lib/sexpr/classes/SheetFill.ts +44 -0
package/lib/sexpr/classes/SheetInstances.ts +168 -0
package/lib/sexpr/classes/SheetInstancesRoot.ts +165 -0
package/lib/sexpr/classes/SheetPin.ts +122 -0
package/lib/sexpr/classes/SheetProperty.ts +115 -0
package/lib/sexpr/classes/SheetSize.ts +44 -0
package/lib/sexpr/classes/Stroke.ts +58 -0
package/lib/sexpr/classes/StrokeType.ts +34 -0
package/lib/sexpr/classes/Symbol.ts +1541 -0
package/lib/sexpr/classes/TextEffects.ts +444 -0
package/lib/sexpr/classes/TitleBlock.ts +352 -0
package/lib/sexpr/classes/Unit.ts +28 -0
package/lib/sexpr/classes/Uuid.ts +8 -0
package/lib/sexpr/classes/Via.ts +328 -0
package/lib/sexpr/classes/ViaNet.ts +59 -0
package/lib/sexpr/classes/Width.ts +8 -0
package/lib/sexpr/classes/Wire.ts +91 -0
package/lib/sexpr/classes/Xy.ts +35 -0
package/lib/sexpr/classes/Zone.ts +41 -0
package/lib/sexpr/index.ts +130 -0
package/lib/sexpr/parseKicadSexpr.ts +5 -0
package/lib/sexpr/parseToPrimitiveSExpr.ts +240 -0
package/lib/sexpr/utils/indentLines.ts +3 -0
package/lib/sexpr/utils/parseYesNo.ts +12 -0
package/lib/sexpr/utils/quoteSExprString.ts +8 -0
package/lib/sexpr/utils/strokeFromArgs.ts +19 -0
package/lib/sexpr/utils/toNumberValue.ts +13 -0
package/lib/sexpr/utils/toStringValue.ts +10 -0
package/package.json +26 -0
package/scripts/download-references.ts +66 -0
package/tests/fixtures/expectEqualPrimitiveSExpr.ts +200 -0
package/tests/sexpr/KicadPcbDemos.test.ts +48 -0
package/tests/sexpr/KicadSchDemos.test.ts +49 -0
package/tests/sexpr/classes/Footprint.test.ts +277 -0
package/tests/sexpr/classes/FootprintPad.test.ts +71 -0
package/tests/sexpr/classes/FpArc.test.ts +45 -0
package/tests/sexpr/classes/FpCircle.test.ts +39 -0
package/tests/sexpr/classes/FpPoly.test.ts +43 -0
package/tests/sexpr/classes/FpRect.test.ts +40 -0
package/tests/sexpr/classes/FpTextBox.test.ts +84 -0
package/tests/sexpr/classes/Image.test.ts +50 -0
package/tests/sexpr/classes/KicadSch.test.ts +97 -0
package/tests/sexpr/classes/Paper.test.ts +30 -0
package/tests/sexpr/classes/Property.test.ts +48 -0
package/tests/sexpr/classes/Setup.test.ts +189 -0
package/tests/sexpr/classes/Sheet.test.ts +107 -0
package/tests/sexpr/classes/Stroke.test.ts +15 -0
package/tests/sexpr/classes/Symbol.test.ts +96 -0
package/tests/sexpr/classes/TextEffects.test.ts +56 -0
package/tests/sexpr/classes/TitleBlock.test.ts +40 -0
package/tsconfig.json +35 -0

package/.cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc ADDED Viewed

@@ -0,0 +1,111 @@
+---
+description: Use Bun instead of Node.js, npm, pnpm, or vite.
+globs: "*.ts, *.tsx, *.html, *.css, *.js, *.jsx, package.json"
+alwaysApply: false
+---
+Default to using Bun instead of Node.js.
+- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
+- Use `bun test` instead of `jest` or `vitest`
+- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
+- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
+- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
+- Bun automatically loads .env, so don't use dotenv.
+## APIs
+- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
+- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
+- `Bun.redis` for Redis. Don't use `ioredis`.
+- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
+- `WebSocket` is built-in. Don't use `ws`.
+- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
+- Bun.$`ls` instead of execa.
+## Testing
+Use `bun test` to run tests.
+```ts#index.test.ts
+import { test, expect } from "bun:test";
+test("hello world", () => {
+  expect(1).toBe(1);
+});
+```
+## Frontend
+Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
+Server:
+```ts#index.ts
+import index from "./index.html"
+Bun.serve({
+  routes: {
+    "/": index,
+    "/api/users/:id": {
+      GET: (req) => {
+        return new Response(JSON.stringify({ id: req.params.id }));
+      },
+    },
+  },
+  // optional websocket support
+  websocket: {
+    open: (ws) => {
+      ws.send("Hello, world!");
+    },
+    message: (ws, message) => {
+      ws.send(message);
+    },
+    close: (ws) => {
+      // handle close
+    }
+  },
+  development: {
+    hmr: true,
+    console: true,
+  }
+})
+```
+HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
+```html#index.html
+<html>
+  <body>
+    <h1>Hello, world!</h1>
+    <script type="module" src="./frontend.tsx"></script>
+  </body>
+</html>
+```
+With the following `frontend.tsx`:
+```tsx#frontend.tsx
+import React from "react";
+// import .css files directly and it works
+import './index.css';
+import { createRoot } from "react-dom/client";
+const root = createRoot(document.body);
+export default function Frontend() {
+  return <h1>Hello, world!</h1>;
+}
+root.render(<Frontend />);
+```
+Then, run index.ts
+```sh
+bun --hot ./index.ts
+```
+For more information, read the Bun API docs in `node_modules/bun-types/docs/**.md`.

package/.vscode/settings.json ADDED Viewed

@@ -0,0 +1,16 @@
+{
+  "workbench.colorCustomizations": {
+    "commandCenter.border": "#15202b99",
+    "sash.hoverBorder": "#18f7e8",
+    "statusBar.background": "#07d5c7",
+    "statusBar.foreground": "#15202b",
+    "statusBarItem.hoverBackground": "#05a499",
+    "statusBarItem.remoteBackground": "#07d5c7",
+    "statusBarItem.remoteForeground": "#15202b",
+    "titleBar.activeBackground": "#07d5c7",
+    "titleBar.activeForeground": "#15202b",
+    "titleBar.inactiveBackground": "#07d5c799",
+    "titleBar.inactiveForeground": "#15202b99"
+  },
+  "peacock.color": "#07d5c7"
+}

package/AGENTS.md ADDED Viewed

@@ -0,0 +1,30 @@
+This is the `kicadts` typescript library. It's still in early developement and
+we're trying to make sure we parse the entire KiCad S-expression specification.
+You can find the difference specifications in the `references` directory, the
+most extensive one is `references/SEXPR_MAIN.adoc` (use `bun run scripts/download-references.ts` to download if it's not already there)
+- `references/SCHEMATIC_SEXPR.adoc`
+- `references/PCB_SEXPR.adoc`
+- `references/FOOTPRINT_SEXPR.adoc`
+- `references/SCH_SYM_SEXPR.adoc`
+- `references/SEXPR_MAIN.adoc`
+### Tips
+- Every S-expression token must have a corresponding `SxClass` subclass and be registered via `SxClass.register`; missing registrations cause parse failures.
+- Tokens reused under different parents (for example `type` under `stroke`) require `static parentToken` overrides so the correct class resolves during parsing.
+- When a class accepts unordered child tokens, set `_propertyMap` using `loadProperties` to make getters convenient and keep `getString()` deterministic.
+- Snapshot tests with `bun test` provide quick verification that `getString()` matches the KiCad formatting expectations.
+### Major Refactor Notice
+- The code in this repo is only partially migrated to the new pattern
+- NEW PATTERN: Constructors never take `PrimitiveSExpr` arguments
+- NEW PATTERN: All classes have a `fromSexprPrimitives` static method that takes a `PrimitiveSExpr` array and returns an instance of the class
+- NEW PATTERN: Classes have ergonomic getters and setters for properties
+- NEW PATTERN: Never has "extras" property, everything becomes an `SxClass`
+- NEW PATTERN: Never have "switch cases" that switch on the token. Always use the `SxClass.parsePrimitiveSexpr` or `SxClass.parsePrimitivesToClassProperties` methods to parse arrays of `PrimitiveSExpr` into instances of the correct class
+- NEW PATTERN: Never track the order of children unless absolutely necessary, use the `_sx*` properties and `getChildren` to return the children in a predefined order
+- NEW PATTERN: Never track unknown children, throw an error/allow an error to be thrown if you encounter a child PrimitiveSExpr that can't be parsed. You can introduce new `_sx*` properties and a new class to prevent the error
+- NEW PATTERN: One class per file

package/README.md ADDED Viewed

@@ -0,0 +1,206 @@
+# kicadts
+`kicadts` is a TypeScript-first toolkit for reading, editing, and generating KiCad S-expression documents. Every KiCad token is modeled as a class, so you can compose schematics, boards, and footprints entirely in TypeScript and emit KiCad-compatible files with deterministic formatting.
+## Local Setup
+This repository uses [Bun](https://bun.sh) for scripts and testing.
+- `bun install`
+- `bun test` — optional, but handy to confirm we still round-trip the KiCad demo files
+## Build KiCad Schematics
+The high-level classes (`KicadSch`, `Sheet`, `SchematicSymbol`, `Wire`, …) expose setters and getters for their children. Populate the model, then call `getString()` to emit KiCad’s S-expression.
+```ts
+import { promises as fs } from "node:fs"
+import {
+  At,
+  KicadSch,
+  Paper,
+  Property,
+  Sheet,
+  SchematicSymbol,
+  TitleBlock,
+  Wire,
+  Pts,
+  Xy,
+} from "kicadts"
+const schematic = new KicadSch()
+schematic.version = 20240101
+schematic.generator = "kicadts-demo"
+const title = new TitleBlock()
+title.title = "Demo Schematic"
+title.company = "Example Labs"
+schematic.titleBlock = title
+const paper = new Paper()
+paper.size = "A4"
+schematic.paper = paper
+schematic.properties = [new Property("Sheetfile", "demo.kicad_sch")]
+const sheet = new Sheet()
+sheet.position = new At([0, 0, 0])
+sheet.size = { width: 100, height: 80 }
+schematic.sheets = [sheet]
+const symbol = new SchematicSymbol()
+symbol.libraryId = "Device:R"
+symbol.at = new At([25.4, 12.7])
+schematic.symbols = [symbol]
+const wire = new Wire()
+wire.points = new Pts([new Xy(0, 0), new Xy(25.4, 12.7)])
+schematic.wires = [wire]
+await fs.writeFile("demo.kicad_sch", schematic.getString())
+```
+## Build KiCad PCBs
+Boards follow the same pattern. Compose `KicadPcb` with nets, footprints, segments, and zones. Footprints are reusable whether you embed them on a board or export them as `.kicad_mod` files.
+```ts
+import { promises as fs } from "node:fs"
+import {
+  At,
+  Footprint,
+  FootprintPad,
+  FpText,
+  KicadPcb,
+  PadLayers,
+  PadNet,
+  PadSize,
+  PcbNet,
+  TextEffects,
+} from "kicadts"
+const pcb = new KicadPcb()
+pcb.version = 20240101
+pcb.generator = "kicadts-demo"
+const netGnd = new PcbNet(1, "GND")
+const netSignal = new PcbNet(2, "Net-(R1-Pad2)")
+pcb.nets = [netGnd, netSignal]
+const footprint = new Footprint()
+footprint.libraryLink = "Resistor_SMD:R_0603"
+footprint.layer = "F.Cu"
+footprint.position = new At([10, 5, 90])
+const makeText = (type: string, text: string, x: number, y: number, layer: string) => {
+  const fpText = new FpText()
+  fpText.type = type
+  fpText.text = text
+  fpText.position = new At([x, y])
+  fpText.layer = layer
+  const effects = new TextEffects()
+  effects.font.size = { height: 1, width: 1 }
+  effects.font.thickness = 0.15
+  fpText.effects = effects
+  return fpText
+}
+footprint.fpTexts = [
+  makeText("reference", "R1", 0, -1.5, "F.SilkS"),
+  makeText("value", "10k", 0, 1.5, "F.Fab"),
+]
+const pad = (number: string, x: number, net: PcbNet) => {
+  const fpPad = new FootprintPad(number, "smd", "roundrect")
+  fpPad.at = new At([x, 0])
+  fpPad.size = new PadSize(1.05, 0.95)
+  fpPad.layers = new PadLayers(["F.Cu", "F.Paste", "F.Mask"])
+  fpPad.roundrectRatio = 0.25
+  fpPad.net = new PadNet(net.id, net.name)
+  fpPad.pinfunction = number
+  fpPad.pintype = "passive"
+  return fpPad
+}
+footprint.fpPads = [pad("1", -0.8, netGnd), pad("2", 0.8, netSignal)]
+pcb.footprints = [footprint]
+await fs.writeFile("demo.kicad_pcb", pcb.getString())
+```
+## Build Stand-Alone Footprints
+Footprints can live outside a board file (for library `.kicad_mod` entries). Populate `Footprint` and write the S-expression to disk.
+```ts
+import { promises as fs } from "node:fs"
+import {
+  At,
+  Footprint,
+  FootprintPad,
+  FpText,
+  PadLayers,
+  PadSize,
+  TextEffects,
+} from "kicadts"
+const footprint = new Footprint()
+footprint.libraryLink = "Demo:TestPad"
+footprint.layer = "F.Cu"
+footprint.position = new At([0, 0])
+const label = new FpText()
+label.type = "reference"
+label.text = "REF**"
+label.position = new At([0, -1.5])
+label.layer = "F.SilkS"
+const effects = new TextEffects()
+effects.font.size = { height: 1, width: 1 }
+effects.font.thickness = 0.15
+label.effects = effects
+footprint.fpTexts = [label]
+const pad = new FootprintPad("1", "smd", "rect")
+pad.at = new At([0, 0])
+pad.size = new PadSize(1.5, 1.5)
+pad.layers = new PadLayers(["F.Cu", "F.Paste", "F.Mask"])
+footprint.fpPads = [pad]
+await fs.writeFile("Demo_TestPad.kicad_mod", footprint.getString())
+```
+## Load Existing KiCad Files
+Parsing works for schematics, boards, footprints, or any KiCad S-expression. `parseKicadSexpr` returns an array of `SxClass` instances; narrow to the concrete class with `instanceof` and mutate as needed.
+```ts
+import { promises as fs } from "node:fs"
+import { KicadPcb, KicadSch, Footprint, parseKicadSexpr } from "kicadts"
+const load = async (path: string) => {
+  const raw = await fs.readFile(path, "utf8")
+  const [root] = parseKicadSexpr(raw)
+  if (root instanceof KicadSch) {
+    root.generator = "kicadts"
+    return root
+  }
+  if (root instanceof KicadPcb) {
+    root.generatorVersion = "(generated programmatically)"
+    return root
+  }
+  if (root instanceof Footprint) {
+    root.descr = "Imported with kicadts"
+    return root
+  }
+  throw new Error(`Unsupported root token: ${root.token}`)
+}
+const updated = await load("existing.kicad_sch")
+await fs.writeFile("existing.kicad_sch", updated.getString())
+```
+Any class exposes `getChildren()` if you need to walk the tree manually, and snapshot tests (`bun test`) ensure the emitted S-expression stays identical to KiCad’s own formatting.

package/biome.json ADDED Viewed

@@ -0,0 +1,93 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
+  "assist": { "actions": { "source": { "organizeImports": "on" } } },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space"
+  },
+  "files": {
+    "includes": ["**", "!**/cosmos-export", "!**/dist", "!**/package.json"]
+  },
+  "javascript": {
+    "formatter": {
+      "jsxQuoteStyle": "double",
+      "quoteProperties": "asNeeded",
+      "trailingCommas": "all",
+      "semicolons": "asNeeded",
+      "arrowParentheses": "always",
+      "bracketSpacing": true,
+      "bracketSameLine": false
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "suspicious": {
+        "noExplicitAny": "off"
+      },
+      "complexity": {
+        "noForEach": "error",
+        "useLiteralKeys": "off"
+      },
+      "a11y": {
+        "noAccessKey": "off",
+        "noAriaHiddenOnFocusable": "off",
+        "noAriaUnsupportedElements": "off",
+        "noAutofocus": "off",
+        "noDistractingElements": "off",
+        "noHeaderScope": "off",
+        "noInteractiveElementToNoninteractiveRole": "off",
+        "noLabelWithoutControl": "off",
+        "noNoninteractiveElementToInteractiveRole": "off",
+        "noNoninteractiveTabindex": "off",
+        "noPositiveTabindex": "off",
+        "noRedundantAlt": "off",
+        "noRedundantRoles": "off",
+        "noStaticElementInteractions": "off",
+        "noSvgWithoutTitle": "off",
+        "useAltText": "off",
+        "useAnchorContent": "off",
+        "useAriaActivedescendantWithTabindex": "off",
+        "useAriaPropsForRole": "off",
+        "useAriaPropsSupportedByRole": "off",
+        "useButtonType": "off",
+        "useFocusableInteractive": "off",
+        "useHeadingContent": "off",
+        "useHtmlLang": "off",
+        "useIframeTitle": "off",
+        "useKeyWithClickEvents": "off",
+        "useKeyWithMouseEvents": "off",
+        "useMediaCaption": "off",
+        "useSemanticElements": "off",
+        "useValidAnchor": "off",
+        "useValidAriaProps": "off",
+        "useValidAriaRole": "off",
+        "useValidAriaValues": "off",
+        "useValidAutocomplete": "off",
+        "useValidLang": "off"
+      },
+      "style": {
+        "useSingleVarDeclarator": "error",
+        "noParameterAssign": "off",
+        "noUselessElse": "off",
+        "noNonNullAssertion": "off",
+        "useNumberNamespace": "off",
+        "noUnusedTemplateLiteral": "off",
+        "useFilenamingConvention": {
+          "level": "error",
+          "options": {
+            "strictCase": true,
+            "requireAscii": true,
+            "filenameCases": ["kebab-case", "export"]
+          }
+        },
+        "useAsConstAssertion": "error",
+        "useDefaultParameterLast": "error",
+        "useEnumInitializers": "error",
+        "useSelfClosingElements": "error",
+        "noInferrableTypes": "error"
+      }
+    }
+  }
+}

package/bun.lock ADDED Viewed

@@ -0,0 +1,48 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "kicadts",
+      "devDependencies": {
+        "@biomejs/biome": "^2.2.4",
+        "@types/bun": "latest",
+      },
+      "peerDependencies": {
+        "typescript": "^5",
+      },
+    },
+  },
+  "packages": {
+    "@biomejs/biome": ["@biomejs/biome@2.2.4", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.2.4", "@biomejs/cli-darwin-x64": "2.2.4", "@biomejs/cli-linux-arm64": "2.2.4", "@biomejs/cli-linux-arm64-musl": "2.2.4", "@biomejs/cli-linux-x64": "2.2.4", "@biomejs/cli-linux-x64-musl": "2.2.4", "@biomejs/cli-win32-arm64": "2.2.4", "@biomejs/cli-win32-x64": "2.2.4" }, "bin": { "biome": "bin/biome" } }, "sha512-TBHU5bUy/Ok6m8c0y3pZiuO/BZoY/OcGxoLlrfQof5s8ISVwbVBdFINPQZyFfKwil8XibYWb7JMwnT8wT4WVPg=="],
+    "@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.2.4", "", { "os": "darwin", "cpu": "arm64" }, "sha512-RJe2uiyaloN4hne4d2+qVj3d3gFJFbmrr5PYtkkjei1O9c+BjGXgpUPVbi8Pl8syumhzJjFsSIYkcLt2VlVLMA=="],
+    "@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.2.4", "", { "os": "darwin", "cpu": "x64" }, "sha512-cFsdB4ePanVWfTnPVaUX+yr8qV8ifxjBKMkZwN7gKb20qXPxd/PmwqUH8mY5wnM9+U0QwM76CxFyBRJhC9tQwg=="],
+    "@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.2.4", "", { "os": "linux", "cpu": "arm64" }, "sha512-M/Iz48p4NAzMXOuH+tsn5BvG/Jb07KOMTdSVwJpicmhN309BeEyRyQX+n1XDF0JVSlu28+hiTQ2L4rZPvu7nMw=="],
+    "@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.2.4", "", { "os": "linux", "cpu": "arm64" }, "sha512-7TNPkMQEWfjvJDaZRSkDCPT/2r5ESFPKx+TEev+I2BXDGIjfCZk2+b88FOhnJNHtksbOZv8ZWnxrA5gyTYhSsQ=="],
+    "@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.2.4", "", { "os": "linux", "cpu": "x64" }, "sha512-orr3nnf2Dpb2ssl6aihQtvcKtLySLta4E2UcXdp7+RTa7mfJjBgIsbS0B9GC8gVu0hjOu021aU8b3/I1tn+pVQ=="],
+    "@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.2.4", "", { "os": "linux", "cpu": "x64" }, "sha512-m41nFDS0ksXK2gwXL6W6yZTYPMH0LughqbsxInSKetoH6morVj43szqKx79Iudkp8WRT5SxSh7qVb8KCUiewGg=="],
+    "@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.2.4", "", { "os": "win32", "cpu": "arm64" }, "sha512-NXnfTeKHDFUWfxAefa57DiGmu9VyKi0cDqFpdI+1hJWQjGJhJutHPX0b5m+eXvTKOaf+brU+P0JrQAZMb5yYaQ=="],
+    "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.2.4", "", { "os": "win32", "cpu": "x64" }, "sha512-3Y4V4zVRarVh/B/eSHczR4LYoSVyv3Dfuvm3cWs5w/HScccS0+Wt/lHOcDTRYeHjQmMYVC3rIRWqyN2EI52+zg=="],
+    "@types/bun": ["@types/bun@1.2.22", "", { "dependencies": { "bun-types": "1.2.22" } }, "sha512-5A/KrKos2ZcN0c6ljRSOa1fYIyCKhZfIVYeuyb4snnvomnpFqC0tTsEkdqNxbAgExV384OETQ//WAjl3XbYqQA=="],
+    "@types/node": ["@types/node@24.5.2", "", { "dependencies": { "undici-types": "~7.12.0" } }, "sha512-FYxk1I7wPv3K2XBaoyH2cTnocQEu8AOZ60hPbsyukMPLv5/5qr7V1i8PLHdl6Zf87I+xZXFvPCXYjiTFq+YSDQ=="],
+    "@types/react": ["@types/react@19.1.13", "", { "dependencies": { "csstype": "^3.0.2" } }, "sha512-hHkbU/eoO3EG5/MZkuFSKmYqPbSVk5byPFa3e7y/8TybHiLMACgI8seVYlicwk7H5K/rI2px9xrQp/C+AUDTiQ=="],
+    "bun-types": ["bun-types@1.2.22", "", { "dependencies": { "@types/node": "*" }, "peerDependencies": { "@types/react": "^19" } }, "sha512-hwaAu8tct/Zn6Zft4U9BsZcXkYomzpHJX28ofvx7k0Zz2HNz54n1n+tDgxoWFGB4PcFvJXJQloPhaV2eP3Q6EA=="],
+    "csstype": ["csstype@3.1.3", "", {}, "sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw=="],
+    "typescript": ["typescript@5.9.2", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-CWBzXQrc/qOkhidw1OzBTQuYRbfyxDXJMVJ1XNwUHGROVmuaeiEm3OslpZ1RV96d7SKKjZKrSJu3+t/xlw3R9A=="],
+    "undici-types": ["undici-types@7.12.0", "", {}, "sha512-goOacqME2GYyOZZfb5Lgtu+1IDmAlAEu5xnD3+xTzS10hT0vzpf0SPjkXwAw9Jm+4n/mQGDP3LO8CPbYROeBfQ=="],
+  }
+}

package/bunfig.toml ADDED Viewed

@@ -0,0 +1,5 @@
+# [test]
+# preload = ["./tests/fixtures/preload.ts"]
+[install.lockfile]
+save = false

package/lib/index.ts ADDED Viewed

	@@ -0,0 +1 @@
1	+ export * from "./sexpr"

package/lib/sexpr/base-classes/SxClass.ts ADDED Viewed

@@ -0,0 +1,164 @@
+import {
+  parseToPrimitiveSExpr,
+  type PrimitiveSExpr,
+} from "../parseToPrimitiveSExpr"
+const DEFAULT_PARENT_TOKEN = "__default__"
+export abstract class SxClass {
+  abstract token: string
+  static token: string
+  /**
+   * Token strings are sometimes re-used (e.g. a "type" token) but the class
+   * varies based on the parent token
+   */
+  static parentToken?: string
+  isSxClass = true
+  getChildren(): SxClass[] {
+    // By default, return any properties found in this instance that have the _sx* prefix
+    return Object.keys(this)
+      .filter((k) => k.startsWith("_sx"))
+      .map((k) => (this as any)[k])
+      .filter((v) => v && typeof v === "object" && v.isSxClass)
+  }
+  getStringIndented(): string {
+    return this.getString()
+      .split("\n")
+      .map((line) => `  ${line}`)
+      .join("\n")
+  }
+  getString(): string {
+    const children = this.getChildren()
+    if (children.length === 0) {
+      return `(${this.token})`
+    }
+    const lines = [`(${this.token}`]
+    for (const p of children) {
+      lines.push(p.getStringIndented())
+    }
+    lines.push(")")
+    return lines.join("\n")
+  }
+  get [Symbol.toStringTag](): string {
+    return this.getString()
+  }
+  [Symbol.for("nodejs.util.inspect.custom")]() {
+    return this.getString()
+  }
+  // =========================== STATIC METHODS ===========================
+  static classes: Record<string, Record<string, any>> = {}
+  /**
+   * Should be called after class definition to register the class for parsing
+   */
+  static register(newClass: any) {
+    if (!newClass.token) {
+      throw new Error("Class must have a static override token")
+    }
+    const parentKey = newClass.parentToken ?? DEFAULT_PARENT_TOKEN
+    const existing = SxClass.classes[newClass.token] ?? {}
+    existing[parentKey] = newClass
+    SxClass.classes[newClass.token] = existing
+  }
+  /**
+   * Parse an S-expression string into registered SxClass instances
+   */
+  static parse(sexpr: string): SxClass[] {
+    const primitiveSexpr = parseToPrimitiveSExpr(sexpr)
+    return SxClass.parsePrimitiveSexpr(primitiveSexpr) as any
+  }
+  static fromSexprPrimitives(primitiveSexprs: PrimitiveSExpr[]): SxClass {
+    throw new Error(
+      `"${this.name}" class has not implemented fromSexprPrimitives`,
+    )
+  }
+  static parsePrimitiveSexpr(
+    primitiveSexpr: PrimitiveSExpr,
+    options: { parentToken?: string } = {},
+  ): SxClass | SxClass[] | number | string | boolean | null {
+    const parentToken = options.parentToken
+    if (
+      Array.isArray(primitiveSexpr) &&
+      primitiveSexpr.length >= 1 &&
+      typeof primitiveSexpr[0] === "string"
+    ) {
+      const classToken = primitiveSexpr[0] as string
+      const classGroup = SxClass.classes[classToken]
+      if (!classGroup) {
+        throw new Error(
+          `Class "${classToken}" not registered via SxClass.register`,
+        )
+      }
+      const parentKey = parentToken ?? DEFAULT_PARENT_TOKEN
+      const ClassDef: any =
+        classGroup[parentKey] ?? classGroup[DEFAULT_PARENT_TOKEN]
+      if (!ClassDef) {
+        throw new Error(
+          `Class "${classToken}" not registered for parent "${parentToken ?? "<root>"}"`,
+        )
+      }
+      const args = primitiveSexpr.slice(1) as PrimitiveSExpr[]
+      if (!("fromSexprPrimitives" in ClassDef)) {
+        throw new Error(
+          `Class "${classToken}" does not have a fromSexprPrimitives method`,
+        )
+      }
+      const classInstance = ClassDef.fromSexprPrimitives(args)
+      return classInstance
+    }
+    if (Array.isArray(primitiveSexpr)) {
+      return primitiveSexpr.map((item) =>
+        SxClass.parsePrimitiveSexpr(item, options),
+      ) as any[]
+    }
+    if (
+      typeof primitiveSexpr === "number" ||
+      typeof primitiveSexpr === "string" ||
+      typeof primitiveSexpr === "boolean" ||
+      primitiveSexpr === null
+    ) {
+      return primitiveSexpr as number | string | boolean | null
+    }
+    throw new Error(
+      `Couldn't parse primitive S-expression: ${JSON.stringify(primitiveSexpr)}`,
+    )
+  }
+  // =========================== STATIC UTILITIES  ===========================
+  static parsePrimitivesToClassProperties(
+    primitiveSexprs: PrimitiveSExpr[],
+    parentToken?: string,
+  ): {
+    propertyMap: Record<string, SxClass>
+    arrayPropertyMap: Record<string, SxClass[]>
+  } {
+    const propertyMap = {} as Record<string, SxClass>
+    const arrayPropertyMap = {} as Record<string, SxClass[]>
+    for (const primitiveSexpr of primitiveSexprs) {
+      const sxClass = SxClass.parsePrimitiveSexpr(primitiveSexpr, {
+        parentToken,
+      }) as SxClass
+      if (!sxClass.isSxClass) continue
+      propertyMap[sxClass.token] = sxClass
+      arrayPropertyMap[sxClass.token] ??= []
+      arrayPropertyMap[sxClass.token]!.push(sxClass)
+    }
+    return { propertyMap, arrayPropertyMap }
+  }
+}