@tscircuit/internal-dynamic-import 0.0.15 → 0.0.17

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 (30) hide show
  1. package/README.md +112 -14
  2. package/dist/index.d.ts +624 -3
  3. package/dist/index.js +72 -28
  4. package/dist/index.js.map +1 -1
  5. package/lib/create-importer.ts +27 -0
  6. package/lib/dynamic-import-resolver.ts +58 -0
  7. package/lib/dynamic-module-registry.ts +37 -0
  8. package/lib/import-urls.ts +27 -0
  9. package/lib/index.ts +46 -0
  10. package/lib/supported-modules.ts +88 -0
  11. package/lib/type-bundles/@tscircuit/circuit-json-schematic-placement-analysis.d.ts +593 -0
  12. package/lib/type-bundles/circuit-json-to-3d-png.d.ts +48 -0
  13. package/lib/type-bundles/circuit-json-to-bom-csv.d.ts +36 -0
  14. package/lib/type-bundles/circuit-json-to-bpc.d.ts +15 -0
  15. package/lib/type-bundles/circuit-json-to-connectivity-map.d.ts +44 -0
  16. package/lib/type-bundles/circuit-json-to-fdm-component-box.d.ts +160 -0
  17. package/lib/type-bundles/circuit-json-to-gerber.d.ts +672 -0
  18. package/lib/type-bundles/circuit-json-to-gltf.d.ts +273 -0
  19. package/lib/type-bundles/circuit-json-to-kicad.d.ts +392 -0
  20. package/lib/type-bundles/circuit-json-to-lbrn.d.ts +54 -0
  21. package/lib/type-bundles/circuit-json-to-pnp-csv.d.ts +15 -0
  22. package/lib/type-bundles/circuit-json-to-readable-netlist.d.ts +5 -0
  23. package/lib/type-bundles/circuit-json-to-simple-3d.d.ts +41 -0
  24. package/lib/type-bundles/circuit-json-to-spice.d.ts +242 -0
  25. package/lib/type-bundles/circuit-json-to-step.d.ts +28 -0
  26. package/lib/type-bundles/circuit-json-to-tscircuit.d.ts +14 -0
  27. package/lib/type-bundles/circuit-to-canvas.d.ts +646 -0
  28. package/lib/type-bundles/circuit-to-svg.d.ts +399 -0
  29. package/lib/type-bundles/kicad-to-circuit-json.d.ts +375 -0
  30. package/package.json +14 -3
package/README.md CHANGED
@@ -1,24 +1,122 @@
1
1
  # @tscircuit/internal-dynamic-import
2
2
 
3
- This module simplifies dynamically importing tscircuit modules, especially when you always want to use the latest version.
3
+ Import supported tscircuit modules with declaration types, or supply your own
4
+ module registry and resolution functions. The default resolver checks a shared
5
+ registry, then loads supported modules from a CDN. Custom resolvers can use
6
+ installed dependencies, lazy imports, or another module source.
4
7
 
5
- It is also approximately type-safe, meaning we package bundled declaration types for a recent version of the supported modules here while leaving the runtime implementation remote.
8
+ ## Default imports
6
9
 
7
- ```tsx
10
+ ```ts
8
11
  import importer from "@tscircuit/internal-dynamic-import"
9
12
 
10
- async function main() {
11
- const { convertSoupToGerberCommands } = await importer("circuit-json-to-gerber")
13
+ const { convertSoupToGerberCommands } = await importer("circuit-json-to-gerber")
14
+ const { CircuitJsonToKicadProConverter } = await importer(
15
+ "circuit-json-to-kicad@0.0.91",
16
+ )
17
+ const { analyzeSchematicPlacement } = await importer(
18
+ "@tscircuit/circuit-json-schematic-placement-analysis@0.0.46",
19
+ )
20
+ ```
21
+
22
+ For a supported module missing from the registry, resolution tries
23
+ its browser entrypoint on `https://jscdn.tscircuit.com`, then `https://esm.run/...`
24
+ if the first import fails. Most packages use `/+esm`; the schematic placement
25
+ analyzer uses its published `/dist/browser.js` bundle. Omitting a version
26
+ requests `latest`; adding `@...` preserves the
27
+ requested version or tag. Unsupported module names reject before a CDN import.
28
+
29
+ Supported-module declarations describe a recent package version, so the default
30
+ importer's types are approximate when loading a different runtime version.
31
+ `getImportUrl`, `getImportUrls`, and `supportedModules` expose the default URL
32
+ and module-name metadata.
33
+
34
+ ## Register an existing module
35
+
36
+ ```ts
37
+ import importer, {
38
+ getDynamicModuleRegistry,
39
+ registerDynamicModule,
40
+ } from "@tscircuit/internal-dynamic-import"
41
+ import * as svgModule from "circuit-to-svg"
42
+
43
+ registerDynamicModule("circuit-to-svg", svgModule)
44
+ const svg = await importer("circuit-to-svg")
45
+
46
+ // The shared registry also contains successful default imports.
47
+ const registry = getDynamicModuleRegistry()
48
+ ```
49
+
50
+ The default resolver checks exact specifier keys in this registry before
51
+ loading remotely. Registering one module does not change resolution for other
52
+ modules. Successful CDN imports are cached under the exact requested specifier;
53
+ a versioned entry does not satisfy another version or a bare-name request.
54
+
55
+ ## Create a lazy module map
56
+
57
+ ```ts
58
+ import { createDynamicImporter } from "@tscircuit/internal-dynamic-import"
59
+
60
+ const loadSvg = () => import("circuit-to-svg")
61
+ const importModule = createDynamicImporter({
62
+ "circuit-to-svg": loadSvg,
63
+ "circuit-to-svg@0.0.447": loadSvg,
64
+ })
12
65
 
13
- // Import a specific version
14
- const { CircuitJsonToKicadProConverter } = await importer(
15
- "circuit-json-to-kicad@0.0.91",
16
- )
66
+ const svg = await importModule("circuit-to-svg")
67
+ ```
68
+
69
+ The factory infers each result type from its loader. Literal imports can be
70
+ included by a bundler; install or pin the dependencies that those loaders use.
71
+ Map keys are exact: the example's versioned key should match the installed
72
+ version, and a request for any other version rejects. Bare names and versioned
73
+ aliases must be declared separately when both should work.
74
+
75
+ Each key loads lazily and caches its successful result. Concurrent requests
76
+ share the pending load. A rejected loader clears that key's pending result so
77
+ the next request retries the same loader. The factory maintains its own cache;
78
+ it does not automatically add modules to the shared eager registry.
79
+
80
+ Missing keys reject unless `createDynamicImporter(loaders, fallback)` receives
81
+ an explicit fallback resolver. The fallback handles missing keys only; it is
82
+ not called when a registered loader fails. The module map may contain custom
83
+ specifier names as well as supported tscircuit packages.
84
+
85
+ ## Replace or extend default resolution
86
+
87
+ ```ts
88
+ import {
89
+ createDynamicImporter,
90
+ setDynamicImportResolver,
91
+ } from "@tscircuit/internal-dynamic-import"
17
92
 
18
- // ...
19
- }
93
+ setDynamicImportResolver(createDynamicImporter({
94
+ "circuit-json-to-bom-csv": () => import("circuit-json-to-bom-csv"),
95
+ "circuit-to-svg": () => import("circuit-to-svg"),
96
+ }))
20
97
  ```
21
98
 
22
- Runtime imports try jscdn first through `https://jscdn.tscircuit.com/.../+esm`
23
- and fall back to `https://esm.run/...` if the jscdn import fails. Omitting a
24
- version uses `latest`; adding `@...` preserves the requested version/tag.
99
+ The default `importer` now delegates to this resolver. The map in this example
100
+ has no fallback, so missing packages or versions reject locally. A custom
101
+ resolver takes precedence over the default registry/CDN lookup.
102
+
103
+ To override selected requests and retain default resolution for others, use
104
+ the supplied `defaultResolver` callback:
105
+
106
+ ```ts
107
+ setDynamicImportResolver((specifier, defaultResolver) => {
108
+ if (specifier === "circuit-to-svg") return import("circuit-to-svg")
109
+ return defaultResolver(specifier)
110
+ })
111
+
112
+ // Restore the default registry/CDN resolver.
113
+ setDynamicImportResolver(undefined)
114
+ ```
115
+
116
+ Registry and resolver configuration are shared within the current JavaScript
117
+ realm. Configure each realm separately before requesting modules. This package
118
+ controls module resolution; supplied modules remain responsible for their own
119
+ requests and runtime assets, such as WASM or fonts.
120
+
121
+ The `@tscircuit/internal-dynamic-import/source` entrypoint exposes TypeScript
122
+ source for consumers that build their own bundle.