@tscircuit/parts-engine 0.0.9 → 0.0.11

package/lib/footprint-translators/get-footprinter-string-from-kicad.ts

@@ -0,0 +1,21 @@
+/**
+ * Transforms a KiCad footprint string into a generic "footprinter string".
+ * For now, this is a simplified conversion to a standard package name.
+ * e.g. "kicad:Resistor_SMD:R_0603_1608Metric" -> "0603"
+ */
+export const getFootprinterStringFromKicad = (
+  kicadFootprint: string,
+): string | undefined => {
+  // kicad:Resistor_SMD:R_0603_1608Metric -> 0603
+  let match = kicadFootprint.match(/:[RC]_(\d{4})_/)
+  if (match) return match[1]
+
+  // kicad:Package_SO:SOIC-8_3.9x4.9mm_P1.27mm -> SOIC-8
+  // kicad:Package_TO_SOT_SMD:SOT-23 -> SOT-23
+  match = kicadFootprint.match(
+    /:(SOIC-\d+|SOT-\d+|SOD-\d+|SSOP-\d+|TSSOP-\d+|QFP-\d+|QFN-\d+)/,
+  )
+  if (match) return match[1]
+
+  return undefined
+}

package/lib/footprint-translators/get-jlc-package-from-footprinter-string.ts

@@ -0,0 +1,12 @@
+/**
+ * Transforms a generic "footprinter string" into a JLC-compatible package name.
+ * e.g. "cap0603" -> "0603"
+ */
+export const getJlcPackageFromFootprinterString = (
+  footprinterString: string,
+): string => {
+  if (footprinterString.includes("cap")) {
+    return footprinterString.replace(/cap/g, "")
+  }
+  return footprinterString
+}

package/lib/footprint-translators/index.ts

@@ -0,0 +1,25 @@
+import { getFootprinterStringFromKicad } from "./get-footprinter-string-from-kicad"
+import { getJlcPackageFromFootprinterString } from "./get-jlc-package-from-footprinter-string"
+
+/**
+ * Get a JLC-compatible package name from a footprint string, which could be
+ * a KiCad footprint or a generic "footprinter string".
+ */
+export const getJlcpcbPackageName = (
+  footprint: string | undefined,
+): string | undefined => {
+  if (!footprint) return undefined
+
+  if (footprint.startsWith("kicad:")) {
+    const footprinterString = getFootprinterStringFromKicad(footprint)
+    if (footprinterString) {
+      return getJlcPackageFromFootprinterString(footprinterString)
+    }
+
+    // Fallback for un-matched KiCad strings
+    return footprint
+  }
+
+  // Not a KiCad string, assume it's a footprinter string
+  return getJlcPackageFromFootprinterString(footprint)
+}

package/lib/jlc-parts-engine.ts

@@ -1,6 +1,7 @@
 import type { PartsEngine, SupplierPartNumbers } from "@tscircuit/props"
+import { getJlcpcbPackageName } from "./footprint-translators/index"
 
-const cache = new Map<string, any>()
+export const cache = new Map<string, any>()
 
 const getJlcPartsCached = async (name: any, params: any) => {
   const paramString = new URLSearchParams({
@@ -18,37 +19,47 @@ const getJlcPartsCached = async (name: any, params: any) => {
   return responseJson
 }
 
+const withBasicPartPreference = (parts: any[] | undefined) => {
+  if (!parts) return []
+  return [...parts].sort(
+    (a, b) => Number(b.is_basic ?? false) - Number(a.is_basic ?? false),
+  )
+}
+
 export const jlcPartsEngine: PartsEngine = {
   findPart: async ({
     sourceComponent,
     footprinterString,
   }): Promise<SupplierPartNumbers> => {
+    const jlcpcbPackage = getJlcpcbPackageName(footprinterString)
+
     if (
       sourceComponent.type === "source_component" &&
       sourceComponent.ftype === "simple_resistor"
     ) {
       const { resistors } = await getJlcPartsCached("resistors", {
         resistance: sourceComponent.resistance,
-        package: footprinterString,
+        package: jlcpcbPackage,
       })
 
       return {
-        jlcpcb: (resistors ?? []).map((r: any) => `C${r.lcsc}`).slice(0, 3),
+        jlcpcb: withBasicPartPreference(resistors)
+          .map((r: any) => `C${r.lcsc}`)
+          .slice(0, 3),
       }
     } else if (
       sourceComponent.type === "source_component" &&
       sourceComponent.ftype === "simple_capacitor"
     ) {
-      if (footprinterString?.includes("cap")) {
-        footprinterString = footprinterString.replace("cap", "")
-      }
       const { capacitors } = await getJlcPartsCached("capacitors", {
         capacitance: sourceComponent.capacitance,
-        package: footprinterString,
+        package: jlcpcbPackage,
       })
 
       return {
-        jlcpcb: (capacitors ?? []).map((c: any) => `C${c.lcsc}`).slice(0, 3),
+        jlcpcb: withBasicPartPreference(capacitors)
+          .map((c: any) => `C${c.lcsc}`)
+          .slice(0, 3),
       }
     } else if (
       sourceComponent.type === "source_component" &&
@@ -72,7 +83,9 @@ export const jlcPartsEngine: PartsEngine = {
             },
       )
       return {
-        jlcpcb: (headers ?? []).map((h: any) => `C${h.lcsc}`).slice(0, 3),
+        jlcpcb: withBasicPartPreference(headers)
+          .map((h: any) => `C${h.lcsc}`)
+          .slice(0, 3),
       }
     } else if (
       sourceComponent.type === "source_component" &&
@@ -80,10 +93,10 @@ export const jlcPartsEngine: PartsEngine = {
     ) {
       const { potentiometers } = await getJlcPartsCached("potentiometers", {
         resistance: sourceComponent.max_resistance,
-        package: footprinterString,
+        package: jlcpcbPackage,
       })
       return {
-        jlcpcb: (potentiometers ?? [])
+        jlcpcb: withBasicPartPreference(potentiometers)
           .map((p: any) => `C${p.lcsc}`)
           .slice(0, 3),
       }
@@ -92,31 +105,37 @@ export const jlcPartsEngine: PartsEngine = {
       sourceComponent.ftype === "simple_diode"
     ) {
       const { diodes } = await getJlcPartsCached("diodes", {
-        package: footprinterString,
+        package: jlcpcbPackage,
       })
       return {
-        jlcpcb: (diodes ?? []).map((d: any) => `C${d.lcsc}`).slice(0, 3),
+        jlcpcb: withBasicPartPreference(diodes)
+          .map((d: any) => `C${d.lcsc}`)
+          .slice(0, 3),
       }
     } else if (
       sourceComponent.type === "source_component" &&
       sourceComponent.ftype === "simple_chip"
     ) {
       const { chips } = await getJlcPartsCached("chips", {
-        package: footprinterString,
+        package: jlcpcbPackage,
       })
       return {
-        jlcpcb: (chips ?? []).map((c: any) => `C${c.lcsc}`).slice(0, 3),
+        jlcpcb: withBasicPartPreference(chips)
+          .map((c: any) => `C${c.lcsc}`)
+          .slice(0, 3),
       }
     } else if (
       sourceComponent.type === "source_component" &&
       sourceComponent.ftype === "simple_transistor"
     ) {
       const { transistors } = await getJlcPartsCached("transistors", {
-        package: footprinterString,
+        package: jlcpcbPackage,
         transistor_type: sourceComponent.transistor_type,
       })
       return {
-        jlcpcb: (transistors ?? []).map((t: any) => `C${t.lcsc}`).slice(0, 3),
+        jlcpcb: withBasicPartPreference(transistors)
+          .map((t: any) => `C${t.lcsc}`)
+          .slice(0, 3),
       }
     } else if (
       sourceComponent.type === "source_component" &&
@@ -124,10 +143,12 @@ export const jlcPartsEngine: PartsEngine = {
     ) {
       const { power_sources } = await getJlcPartsCached("power_sources", {
         voltage: sourceComponent.voltage,
-        package: footprinterString,
+        package: jlcpcbPackage,
       })
       return {
-        jlcpcb: (power_sources ?? []).map((p: any) => `C${p.lcsc}`).slice(0, 3),
+        jlcpcb: withBasicPartPreference(power_sources)
+          .map((p: any) => `C${p.lcsc}`)
+          .slice(0, 3),
       }
     } else if (
       sourceComponent.type === "source_component" &&
@@ -135,10 +156,12 @@ export const jlcPartsEngine: PartsEngine = {
     ) {
       const { inductors } = await getJlcPartsCached("inductors", {
         inductance: sourceComponent.inductance,
-        package: footprinterString,
+        package: jlcpcbPackage,
       })
       return {
-        jlcpcb: (inductors ?? []).map((i: any) => `C${i.lcsc}`).slice(0, 3),
+        jlcpcb: withBasicPartPreference(inductors)
+          .map((i: any) => `C${i.lcsc}`)
+          .slice(0, 3),
       }
     } else if (
       sourceComponent.type === "source_component" &&
@@ -147,22 +170,26 @@ export const jlcPartsEngine: PartsEngine = {
       const { crystals } = await getJlcPartsCached("crystals", {
         frequency: sourceComponent.frequency,
         load_capacitance: sourceComponent.load_capacitance,
-        package: footprinterString,
+        package: jlcpcbPackage,
       })
       return {
-        jlcpcb: (crystals ?? []).map((c: any) => `C${c.lcsc}`).slice(0, 3),
+        jlcpcb: withBasicPartPreference(crystals)
+          .map((c: any) => `C${c.lcsc}`)
+          .slice(0, 3),
       }
     } else if (
       sourceComponent.type === "source_component" &&
       sourceComponent.ftype === "simple_mosfet"
     ) {
       const { mosfets } = await getJlcPartsCached("mosfets", {
-        package: footprinterString,
+        package: jlcpcbPackage,
         mosfet_mode: sourceComponent.mosfet_mode,
         channel_type: sourceComponent.channel_type,
       })
       return {
-        jlcpcb: (mosfets ?? []).map((m: any) => `C${m.lcsc}`).slice(0, 3),
+        jlcpcb: withBasicPartPreference(mosfets)
+          .map((m: any) => `C${m.lcsc}`)
+          .slice(0, 3),
       }
     } else if (
       sourceComponent.type === "source_component" &&
@@ -170,10 +197,12 @@ export const jlcPartsEngine: PartsEngine = {
     ) {
       const { resonators } = await getJlcPartsCached("resonators", {
         frequency: sourceComponent.frequency,
-        package: footprinterString,
+        package: jlcpcbPackage,
       })
       return {
-        jlcpcb: (resonators ?? []).map((r: any) => `C${r.lcsc}`).slice(0, 3),
+        jlcpcb: withBasicPartPreference(resonators)
+          .map((r: any) => `C${r.lcsc}`)
+          .slice(0, 3),
       }
     } else if (
       sourceComponent.type === "source_component" &&
@@ -181,30 +210,36 @@ export const jlcPartsEngine: PartsEngine = {
     ) {
       const { switches } = await getJlcPartsCached("switches", {
         switch_type: sourceComponent.type,
-        package: footprinterString,
+        package: jlcpcbPackage,
       })
       return {
-        jlcpcb: (switches ?? []).map((s: any) => `C${s.lcsc}`).slice(0, 3),
+        jlcpcb: withBasicPartPreference(switches)
+          .map((s: any) => `C${s.lcsc}`)
+          .slice(0, 3),
       }
     } else if (
       sourceComponent.type === "source_component" &&
       sourceComponent.ftype === "simple_led"
     ) {
       const { leds } = await getJlcPartsCached("leds", {
-        package: footprinterString,
+        package: jlcpcbPackage,
       })
       return {
-        jlcpcb: (leds ?? []).map((l: any) => `C${l.lcsc}`).slice(0, 3),
+        jlcpcb: withBasicPartPreference(leds)
+          .map((l: any) => `C${l.lcsc}`)
+          .slice(0, 3),
       }
     } else if (
       sourceComponent.type === "source_component" &&
       sourceComponent.ftype === "simple_fuse"
     ) {
       const { fuses } = await getJlcPartsCached("fuses", {
-        package: footprinterString,
+        package: jlcpcbPackage,
       })
       return {
-        jlcpcb: (fuses ?? []).map((l: any) => `C${l.lcsc}`).slice(0, 3),
+        jlcpcb: withBasicPartPreference(fuses)
+          .map((l: any) => `C${l.lcsc}`)
+          .slice(0, 3),
       }
     }
     return {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tscircuit/parts-engine",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "type": "module",
   "main": "./dist/index.js",
   "devDependencies": {

package/tests/jlc-parts-engine.test.ts

@@ -1,8 +1,9 @@
 import { describe, test, expect, beforeEach } from "bun:test"
-import { jlcPartsEngine } from "../lib/jlc-parts-engine"
+import { jlcPartsEngine, cache } from "../lib/jlc-parts-engine"
 import type { AnySourceComponent } from "circuit-json"
 describe("jlcPartsEngine", () => {
   beforeEach(() => {
+    cache.clear()
     // Reset fetch fake between tests
     globalThis.fetch = (async (url: string) => {
       if (url.includes("/resistors/")) {
@@ -127,6 +128,25 @@ describe("jlcPartsEngine", () => {
     })
   })
 
+  test("should find resistor parts with kicad footprint", async () => {
+    const resistor: AnySourceComponent = {
+      type: "source_component",
+      ftype: "simple_resistor",
+      resistance: 10000,
+      source_component_id: "source_component_0",
+      name: "R1",
+    }
+
+    const result = await jlcPartsEngine.findPart({
+      sourceComponent: resistor,
+      footprinterString: "kicad:Resistor_SMD:R_0603_1608Metric",
+    })
+
+    expect(result).toEqual({
+      jlcpcb: ["C1234", "C5678", "C9012"],
+    })
+  })
+
   test("should find capacitor parts", async () => {
     const capacitor: AnySourceComponent = {
       type: "source_component",
@@ -138,7 +158,7 @@ describe("jlcPartsEngine", () => {
 
     const result = await jlcPartsEngine.findPart({
       sourceComponent: capacitor,
-      footprinterString: "0603cap",
+      footprinterString: "cap0603",
     })
 
     expect(result).toEqual({
@@ -222,6 +242,24 @@ describe("jlcPartsEngine", () => {
     })
   })
 
+  test("should find chip parts with kicad footprint", async () => {
+    const chip: AnySourceComponent = {
+      type: "source_component",
+      ftype: "simple_chip",
+      source_component_id: "source_component_0",
+      name: "U1",
+    }
+
+    const result = await jlcPartsEngine.findPart({
+      sourceComponent: chip,
+      footprinterString: "kicad:Package_SO:SOIC-8_3.9x4.9mm_P1.27mm",
+    })
+
+    expect(result).toEqual({
+      jlcpcb: ["C5678", "C9012", "C3456"],
+    })
+  })
+
   test("should find transistor parts", async () => {
     const transistor: AnySourceComponent = {
       type: "source_component",
@@ -394,4 +432,42 @@ describe("jlcPartsEngine", () => {
 
     expect(result).toEqual({ jlcpcb: [] })
   })
+
+  test("should prefer basic parts when available", async () => {
+    // Override the global fetch mock for this specific test
+    globalThis.fetch = (async (url: string) => {
+      if (url.includes("/resistors/")) {
+        return {
+          json: async () => ({
+            resistors: [
+              { lcsc: "1111" }, // is_basic is undefined, treated as false
+              { lcsc: "2222", is_basic: true },
+              { lcsc: "3333", is_basic: false },
+              { lcsc: "4444", is_basic: true },
+              { lcsc: "5555" },
+            ],
+          }),
+        } as Response
+      }
+      return {} as Response
+    }) as unknown as typeof fetch
+
+    const resistor: AnySourceComponent = {
+      type: "source_component",
+      ftype: "simple_resistor",
+      resistance: 10000,
+      source_component_id: "source_component_0",
+      name: "R1",
+    }
+
+    const result = await jlcPartsEngine.findPart({
+      sourceComponent: resistor,
+      footprinterString: "0603",
+    })
+
+    // Expecting basic parts to be prioritized
+    expect(result).toEqual({
+      jlcpcb: ["C2222", "C4444", "C1111"],
+    })
+  })
 })