sandlot 0.1.4 → 0.2.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 (115) hide show
  1. package/dist/browser/bundler.d.ts +68 -0
  2. package/dist/browser/bundler.d.ts.map +1 -0
  3. package/dist/browser/executor.d.ts +46 -0
  4. package/dist/browser/executor.d.ts.map +1 -0
  5. package/dist/browser/index.d.ts +9 -0
  6. package/dist/browser/index.d.ts.map +1 -0
  7. package/dist/browser/index.js +2690 -0
  8. package/dist/browser/preset.d.ts +63 -0
  9. package/dist/browser/preset.d.ts.map +1 -0
  10. package/dist/commands/index.d.ts +20 -11
  11. package/dist/commands/index.d.ts.map +1 -1
  12. package/dist/commands/types.d.ts +37 -130
  13. package/dist/commands/types.d.ts.map +1 -1
  14. package/dist/core/bundler-utils.d.ts +142 -0
  15. package/dist/core/bundler-utils.d.ts.map +1 -0
  16. package/dist/core/esm-types-resolver.d.ts +125 -0
  17. package/dist/core/esm-types-resolver.d.ts.map +1 -0
  18. package/dist/core/executor.d.ts +35 -0
  19. package/dist/core/executor.d.ts.map +1 -0
  20. package/dist/{fs.d.ts → core/fs.d.ts} +27 -29
  21. package/dist/core/fs.d.ts.map +1 -0
  22. package/dist/core/sandbox.d.ts +30 -0
  23. package/dist/core/sandbox.d.ts.map +1 -0
  24. package/dist/core/sandlot.d.ts +30 -0
  25. package/dist/core/sandlot.d.ts.map +1 -0
  26. package/dist/core/shared-module-registry.d.ts +46 -0
  27. package/dist/core/shared-module-registry.d.ts.map +1 -0
  28. package/dist/core/typechecker.d.ts +60 -0
  29. package/dist/core/typechecker.d.ts.map +1 -0
  30. package/dist/index.d.ts +11 -16
  31. package/dist/index.d.ts.map +1 -1
  32. package/dist/index.js +1398 -2010
  33. package/dist/node/bundler.d.ts +48 -0
  34. package/dist/node/bundler.d.ts.map +1 -0
  35. package/dist/node/executor.d.ts +48 -0
  36. package/dist/node/executor.d.ts.map +1 -0
  37. package/dist/node/index.d.ts +9 -0
  38. package/dist/node/index.d.ts.map +1 -0
  39. package/dist/node/index.js +2644 -0
  40. package/dist/node/preset.d.ts +62 -0
  41. package/dist/node/preset.d.ts.map +1 -0
  42. package/dist/types.d.ts +528 -0
  43. package/dist/types.d.ts.map +1 -0
  44. package/package.json +16 -6
  45. package/src/browser/bundler.ts +294 -0
  46. package/src/browser/executor.ts +71 -0
  47. package/src/browser/index.ts +57 -0
  48. package/src/browser/preset.ts +179 -0
  49. package/src/commands/index.ts +498 -37
  50. package/src/commands/types.ts +117 -145
  51. package/src/core/bundler-utils.ts +630 -0
  52. package/src/core/esm-types-resolver.ts +432 -0
  53. package/src/core/executor.ts +161 -0
  54. package/src/{fs.ts → core/fs.ts} +59 -37
  55. package/src/core/sandbox.ts +624 -0
  56. package/src/core/sandlot.ts +77 -0
  57. package/src/core/shared-module-registry.ts +138 -0
  58. package/src/core/typechecker.ts +609 -0
  59. package/src/index.ts +106 -139
  60. package/src/node/bundler.ts +194 -0
  61. package/src/node/executor.ts +87 -0
  62. package/src/node/index.ts +39 -0
  63. package/src/node/preset.ts +178 -0
  64. package/src/types.ts +672 -0
  65. package/README.md +0 -243
  66. package/dist/build-emitter.d.ts +0 -47
  67. package/dist/build-emitter.d.ts.map +0 -1
  68. package/dist/builder.d.ts +0 -370
  69. package/dist/builder.d.ts.map +0 -1
  70. package/dist/bundler.d.ts +0 -152
  71. package/dist/bundler.d.ts.map +0 -1
  72. package/dist/commands/compile.d.ts +0 -13
  73. package/dist/commands/compile.d.ts.map +0 -1
  74. package/dist/commands/packages.d.ts +0 -17
  75. package/dist/commands/packages.d.ts.map +0 -1
  76. package/dist/commands/run.d.ts +0 -40
  77. package/dist/commands/run.d.ts.map +0 -1
  78. package/dist/commands.d.ts +0 -179
  79. package/dist/commands.d.ts.map +0 -1
  80. package/dist/fs.d.ts.map +0 -1
  81. package/dist/internal.d.ts +0 -79
  82. package/dist/internal.d.ts.map +0 -1
  83. package/dist/internal.js +0 -1942
  84. package/dist/loader.d.ts +0 -164
  85. package/dist/loader.d.ts.map +0 -1
  86. package/dist/packages.d.ts +0 -199
  87. package/dist/packages.d.ts.map +0 -1
  88. package/dist/runner.d.ts +0 -314
  89. package/dist/runner.d.ts.map +0 -1
  90. package/dist/sandbox-manager.d.ts +0 -261
  91. package/dist/sandbox-manager.d.ts.map +0 -1
  92. package/dist/sandbox.d.ts +0 -267
  93. package/dist/sandbox.d.ts.map +0 -1
  94. package/dist/shared-modules.d.ts +0 -148
  95. package/dist/shared-modules.d.ts.map +0 -1
  96. package/dist/shared-resources.d.ts +0 -102
  97. package/dist/shared-resources.d.ts.map +0 -1
  98. package/dist/ts-libs.d.ts +0 -85
  99. package/dist/ts-libs.d.ts.map +0 -1
  100. package/dist/typechecker.d.ts +0 -127
  101. package/dist/typechecker.d.ts.map +0 -1
  102. package/src/build-emitter.ts +0 -64
  103. package/src/builder.ts +0 -498
  104. package/src/bundler.ts +0 -575
  105. package/src/commands/compile.ts +0 -236
  106. package/src/commands/packages.ts +0 -154
  107. package/src/commands/run.ts +0 -245
  108. package/src/internal.ts +0 -119
  109. package/src/loader.ts +0 -229
  110. package/src/packages.ts +0 -936
  111. package/src/sandbox.ts +0 -398
  112. package/src/shared-modules.ts +0 -280
  113. package/src/shared-resources.ts +0 -166
  114. package/src/ts-libs.ts +0 -218
  115. package/src/typechecker.ts +0 -635
@@ -0,0 +1,62 @@
1
+ import { type EsmTypesResolverOptions } from "../core/esm-types-resolver";
2
+ import type { Sandlot, SandlotOptions } from "../types";
3
+ import { type EsbuildNativeBundlerOptions } from "./bundler";
4
+ import { type TypecheckerOptions } from "../core/typechecker";
5
+ import { type NodeExecutorOptions } from "./executor";
6
+ export interface CreateNodeSandlotOptions extends Omit<SandlotOptions, "bundler" | "typechecker" | "typesResolver" | "executor"> {
7
+ /**
8
+ * Custom bundler options, or a pre-configured bundler instance.
9
+ */
10
+ bundler?: EsbuildNativeBundlerOptions | SandlotOptions["bundler"];
11
+ /**
12
+ * Custom typechecker options, or a pre-configured typechecker instance.
13
+ * Set to `false` to disable type checking.
14
+ */
15
+ typechecker?: TypecheckerOptions | SandlotOptions["typechecker"] | false;
16
+ /**
17
+ * Custom types resolver options, or a pre-configured resolver instance.
18
+ * Set to `false` to disable type resolution.
19
+ */
20
+ typesResolver?: EsmTypesResolverOptions | SandlotOptions["typesResolver"] | false;
21
+ /**
22
+ * Custom executor options, or a pre-configured executor instance.
23
+ * Set to `false` to disable execution (sandbox.run() will throw).
24
+ * Defaults to NodeExecutor.
25
+ */
26
+ executor?: NodeExecutorOptions | SandlotOptions["executor"] | false;
27
+ }
28
+ /**
29
+ * Create a Sandlot instance pre-configured for Node.js/Bun/Deno environments.
30
+ *
31
+ * This is a convenience function that sets up sensible defaults:
32
+ * - EsbuildNativeBundler for bundling (uses native esbuild)
33
+ * - Typechecker for type checking (fetches libs from CDN)
34
+ * - EsmTypesResolver for npm type resolution
35
+ * - NodeExecutor for code execution
36
+ *
37
+ * @example Basic usage
38
+ * ```ts
39
+ * const sandlot = await createNodeSandlot();
40
+ * const sandbox = await sandlot.createSandbox();
41
+ * ```
42
+ *
43
+ * @example With shared modules
44
+ * ```ts
45
+ * import express from "express";
46
+ *
47
+ * const sandlot = await createNodeSandlot({
48
+ * sharedModules: {
49
+ * express,
50
+ * },
51
+ * });
52
+ * ```
53
+ *
54
+ * @example Disable type checking for faster builds
55
+ * ```ts
56
+ * const sandlot = await createNodeSandlot({
57
+ * typechecker: false,
58
+ * });
59
+ * ```
60
+ */
61
+ export declare function createNodeSandlot(options?: CreateNodeSandlotOptions): Promise<Sandlot>;
62
+ //# sourceMappingURL=preset.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"preset.d.ts","sourceRoot":"","sources":["../../src/node/preset.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,EAAwB,KAAK,2BAA2B,EAAE,MAAM,WAAW,CAAC;AACnF,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,wBACf,SAAQ,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,aAAa,GAAG,eAAe,GAAG,UAAU,CAAC;IACtF;;OAEG;IACH,OAAO,CAAC,EAAE,2BAA2B,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;IAElE;;;OAGG;IACH,WAAW,CAAC,EACV,kBAAkB,GAClB,cAAc,CAAC,aAAa,CAAC,GAC7B,KAAK,CAAC;IAER;;;OAGG;IACH,aAAa,CAAC,EACZ,uBAAuB,GACvB,cAAc,CAAC,eAAe,CAAC,GAC/B,KAAK,CAAC;IAER;;;;OAIG;IACH,QAAQ,CAAC,EACP,mBAAmB,GACnB,cAAc,CAAC,UAAU,CAAC,GAC1B,KAAK,CAAC;CACT;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,OAAO,CAAC,CAgDlB"}
@@ -0,0 +1,528 @@
1
+ import type { Filesystem } from "./core/fs";
2
+ export type { IFileSystem, FsEntry, FsStat } from "just-bash/browser";
3
+ export type { Filesystem } from "./core/fs";
4
+ /**
5
+ * Bundler interface - transforms source files into executable JavaScript.
6
+ *
7
+ * Implementations handle their own initialization and caching (e.g., WASM loading).
8
+ */
9
+ export interface IBundler {
10
+ /**
11
+ * Bundle source files from a filesystem into a single output
12
+ */
13
+ bundle(options: BundleOptions): Promise<BundleResult>;
14
+ }
15
+ export interface BundleOptions {
16
+ fs: Filesystem;
17
+ entryPoint: string;
18
+ /**
19
+ * Map of installed package names to versions.
20
+ * Used by the bundler to resolve imports to specific versions.
21
+ *
22
+ * @example { "lodash": "4.17.21", "react": "18.2.0" }
23
+ */
24
+ installedPackages?: Record<string, string>;
25
+ /**
26
+ * Module IDs that resolve to shared modules instead of bundling.
27
+ * These are provided by the host environment at runtime.
28
+ */
29
+ sharedModules?: string[];
30
+ /** Shared module registry for resolving shared imports */
31
+ sharedModuleRegistry?: ISharedModuleRegistry;
32
+ /** Modules to treat as external (don't bundle or rewrite) */
33
+ external?: string[];
34
+ format?: "esm" | "iife" | "cjs";
35
+ minify?: boolean;
36
+ sourcemap?: boolean;
37
+ target?: string[];
38
+ }
39
+ /**
40
+ * Bundle result - success or failure with structured errors.
41
+ */
42
+ export type BundleResult = BundleSuccess | BundleFailure;
43
+ export interface BundleSuccess {
44
+ success: true;
45
+ code: string;
46
+ warnings: BundleWarning[];
47
+ includedFiles: string[];
48
+ }
49
+ export interface BundleFailure {
50
+ success: false;
51
+ errors: BundleError[];
52
+ warnings: BundleWarning[];
53
+ }
54
+ export interface BundleWarning {
55
+ text: string;
56
+ location?: BundleLocation;
57
+ }
58
+ export interface BundleError {
59
+ text: string;
60
+ location?: BundleLocation;
61
+ }
62
+ export interface BundleLocation {
63
+ file: string;
64
+ line: number;
65
+ column?: number;
66
+ /** The source line text (if available from esbuild) */
67
+ lineText?: string;
68
+ }
69
+ /**
70
+ * Typechecker interface - validates TypeScript code.
71
+ *
72
+ * Implementations handle their own lib file loading and caching.
73
+ */
74
+ export interface ITypechecker {
75
+ /**
76
+ * Type check files against a virtual filesystem
77
+ */
78
+ typecheck(options: TypecheckOptions): Promise<TypecheckResult>;
79
+ }
80
+ export interface TypecheckOptions {
81
+ /** Sync filesystem to read source files from */
82
+ fs: Filesystem;
83
+ /** Entry point path (absolute path in the filesystem) */
84
+ entryPoint: string;
85
+ /** Path to tsconfig.json (default: "/tsconfig.json") */
86
+ tsconfigPath?: string;
87
+ }
88
+ export interface TypecheckResult {
89
+ success: boolean;
90
+ diagnostics: Diagnostic[];
91
+ }
92
+ export interface Diagnostic {
93
+ file?: string;
94
+ line?: number;
95
+ column?: number;
96
+ message: string;
97
+ severity: "error" | "warning" | "info";
98
+ }
99
+ /**
100
+ * Types resolver interface - fetches type definitions for npm packages.
101
+ *
102
+ * Implementations handle their own caching (in-memory, KV, R2, etc.).
103
+ */
104
+ export interface ITypesResolver {
105
+ /**
106
+ * Fetch type definitions for a package.
107
+ * Returns a map of file paths to content for .d.ts files.
108
+ */
109
+ resolveTypes(packageName: string, version?: string): Promise<Record<string, string>>;
110
+ }
111
+ /**
112
+ * Shared module registry interface - provides host modules to bundled code.
113
+ *
114
+ * This allows dynamic code to use the same React/library instances as the host,
115
+ * avoiding the "multiple React instances" problem.
116
+ *
117
+ * Each registry instance has a unique key for global exposure, allowing multiple
118
+ * Sandlot instances to coexist without sharing module state.
119
+ */
120
+ export interface ISharedModuleRegistry {
121
+ /**
122
+ * The unique global key where this registry is exposed.
123
+ * Bundled code accesses the registry via `globalThis[registryKey]`.
124
+ */
125
+ readonly registryKey: string;
126
+ /**
127
+ * Get a registered module by ID
128
+ */
129
+ get(moduleId: string): unknown;
130
+ /**
131
+ * Check if a module is registered
132
+ */
133
+ has(moduleId: string): boolean;
134
+ /**
135
+ * Get export names for a module (for generating re-exports)
136
+ */
137
+ getExportNames(moduleId: string): string[];
138
+ /**
139
+ * List all registered module IDs
140
+ */
141
+ list(): string[];
142
+ }
143
+ /**
144
+ * Executor interface - runs bundled code in an isolated context.
145
+ *
146
+ * Different implementations provide different isolation levels:
147
+ * - MainThreadExecutor: Runs in the main thread (no isolation, for trusted code)
148
+ * - WorkerExecutor: Runs in a Web Worker (memory isolation, can be terminated)
149
+ * - IframeExecutor: Runs in a sandboxed iframe (DOM isolation, CSP control)
150
+ *
151
+ * The executor receives a code string (bundled JavaScript) and options,
152
+ * and returns the execution result including captured logs and return value.
153
+ */
154
+ export interface IExecutor {
155
+ /**
156
+ * Execute bundled code and return the result.
157
+ *
158
+ * @param code - The bundled JavaScript code to execute
159
+ * @param options - Execution options (entry export, context, timeout)
160
+ * @returns Execution result with logs, return value, and any error
161
+ */
162
+ execute(code: string, options?: ExecuteOptions): Promise<ExecuteResult>;
163
+ }
164
+ /**
165
+ * Options for code execution.
166
+ */
167
+ export interface ExecuteOptions {
168
+ /**
169
+ * Which export to call:
170
+ * - 'main': Calls `main(context)` export with the provided context
171
+ * - 'default': Calls the default export (no arguments)
172
+ *
173
+ * If neither export exists, top-level code still runs on import.
174
+ * @default 'main'
175
+ */
176
+ entryExport?: "main" | "default";
177
+ /**
178
+ * Context object passed to `main(context)` when entryExport is 'main'.
179
+ * Typically includes things like args, env, logging functions.
180
+ */
181
+ context?: Record<string, unknown>;
182
+ /**
183
+ * Execution timeout in milliseconds.
184
+ * Set to 0 to disable timeout.
185
+ * @default 30000
186
+ */
187
+ timeout?: number;
188
+ }
189
+ /**
190
+ * Result of code execution.
191
+ */
192
+ export interface ExecuteResult {
193
+ /** Whether execution completed successfully */
194
+ success: boolean;
195
+ /** Captured console output (log, warn, error, info, debug) */
196
+ logs: string[];
197
+ /** Return value from the executed function (if any) */
198
+ returnValue?: unknown;
199
+ /** Error message if execution failed */
200
+ error?: string;
201
+ /** Execution time in milliseconds */
202
+ executionTimeMs?: number;
203
+ }
204
+ export interface SandlotOptions {
205
+ /**
206
+ * Bundler implementation.
207
+ * Handles its own initialization and WASM loading.
208
+ */
209
+ bundler: IBundler;
210
+ /**
211
+ * Executor implementation (optional).
212
+ * Handles running bundled code in an appropriate context.
213
+ * If not provided, sandbox.run() will throw an error.
214
+ */
215
+ executor?: IExecutor;
216
+ /**
217
+ * Typechecker implementation (optional - skip type checking if not provided).
218
+ * Handles its own TypeScript lib file loading and caching.
219
+ */
220
+ typechecker?: ITypechecker;
221
+ /**
222
+ * Types resolver for npm packages (optional).
223
+ * Handles its own caching. If not provided, `install` command won't fetch types.
224
+ */
225
+ typesResolver?: ITypesResolver;
226
+ /**
227
+ * Shared modules - host modules to share with sandboxed code.
228
+ * Keys are import specifiers, values are the actual module objects.
229
+ *
230
+ * @example { 'react': React, 'react-dom/client': ReactDOM }
231
+ */
232
+ sharedModules?: Record<string, unknown>;
233
+ /**
234
+ * Default options for sandboxes created from this instance
235
+ */
236
+ sandboxDefaults?: {
237
+ maxFilesystemSize?: number;
238
+ };
239
+ }
240
+ export interface SandboxOptions {
241
+ /**
242
+ * Initial files to populate the filesystem with.
243
+ *
244
+ * If `/package.json` is not provided, a default one will be created with:
245
+ * ```json
246
+ * { "main": "./index.ts", "dependencies": {} }
247
+ * ```
248
+ *
249
+ * If `/tsconfig.json` is not provided, sensible defaults will be created.
250
+ *
251
+ * The `main` field in package.json determines the entry point for build/typecheck.
252
+ */
253
+ initialFiles?: Record<string, string>;
254
+ /**
255
+ * Maximum filesystem size in bytes
256
+ */
257
+ maxFilesystemSize?: number;
258
+ /**
259
+ * Callback invoked when a build succeeds
260
+ */
261
+ onBuild?: (result: BuildSuccess) => void | Promise<void>;
262
+ }
263
+ /**
264
+ * Build phases that can fail.
265
+ */
266
+ export type BuildPhase = "entry" | "typecheck" | "bundle";
267
+ /**
268
+ * Build result - success or failure with structured errors.
269
+ *
270
+ * On success, contains the bundled code string.
271
+ * On failure, contains the phase that failed and structured error information.
272
+ *
273
+ * Note: Build does NOT load or execute the module. Use an executor to run the code.
274
+ * This keeps the build phase pure (no code execution) and allows different execution
275
+ * contexts (main thread, web worker, iframe, remote server).
276
+ */
277
+ export type BuildResult = BuildSuccess | BuildFailure;
278
+ export interface BuildSuccess {
279
+ success: true;
280
+ /** The bundled JavaScript code */
281
+ code: string;
282
+ /** Files that were included in the bundle */
283
+ includedFiles: string[];
284
+ /** Any warnings from the bundler */
285
+ warnings: BundleWarning[];
286
+ }
287
+ /**
288
+ * Details about why a build failed.
289
+ * Used by both BuildResult and RunResult.
290
+ */
291
+ export interface BuildFailureDetails {
292
+ /** Which phase of the build failed */
293
+ phase: BuildPhase;
294
+ /** Error message (for entry failures) */
295
+ message?: string;
296
+ /** Type check diagnostics (for typecheck failures) */
297
+ diagnostics?: Diagnostic[];
298
+ /** Bundle errors (for bundle failures) */
299
+ bundleErrors?: BundleError[];
300
+ /** Bundle warnings (may be present even on failure) */
301
+ bundleWarnings?: BundleWarning[];
302
+ }
303
+ export interface BuildFailure extends BuildFailureDetails {
304
+ success: false;
305
+ }
306
+ export interface InstallResult {
307
+ /** Package name */
308
+ name: string;
309
+ /** Resolved version */
310
+ version: string;
311
+ /** Whether type definitions were installed */
312
+ typesInstalled: boolean;
313
+ /** Number of .d.ts files written */
314
+ typeFilesCount: number;
315
+ /** Whether types came from cache */
316
+ fromCache?: boolean;
317
+ /** Error message if types failed to install */
318
+ typesError?: string;
319
+ }
320
+ export interface UninstallResult {
321
+ /** Package name */
322
+ name: string;
323
+ /** Whether the package was installed (and thus removed) */
324
+ removed: boolean;
325
+ }
326
+ export interface SandboxBuildOptions {
327
+ /**
328
+ * Entry point to build.
329
+ * If not specified, reads from `main` field in /package.json.
330
+ * Falls back to "./index.ts" if not found.
331
+ */
332
+ entryPoint?: string;
333
+ /**
334
+ * Skip type checking before bundling.
335
+ * @default false
336
+ */
337
+ skipTypecheck?: boolean;
338
+ /**
339
+ * Minify the output.
340
+ * @default false
341
+ */
342
+ minify?: boolean;
343
+ /**
344
+ * Output format.
345
+ * @default "esm"
346
+ */
347
+ format?: "esm" | "iife" | "cjs";
348
+ }
349
+ export interface SandboxTypecheckOptions {
350
+ /**
351
+ * Entry point to typecheck.
352
+ * If not specified, reads from `main` field in /package.json.
353
+ * Falls back to "./index.ts" if not found.
354
+ */
355
+ entryPoint?: string;
356
+ }
357
+ /**
358
+ * Options for running code in the sandbox.
359
+ */
360
+ export interface RunOptions {
361
+ /**
362
+ * Entry point to build and run.
363
+ * If not specified, reads from `main` field in /package.json.
364
+ * Falls back to "./index.ts" if not found.
365
+ */
366
+ entryPoint?: string;
367
+ /**
368
+ * Skip type checking before building.
369
+ * @default false
370
+ */
371
+ skipTypecheck?: boolean;
372
+ /**
373
+ * Which export to call:
374
+ * - 'main': Calls `main(context)` export with the provided context
375
+ * - 'default': Calls the default export (no arguments)
376
+ * @default 'main'
377
+ */
378
+ entryExport?: "main" | "default";
379
+ /**
380
+ * Context object passed to `main(context)` when entryExport is 'main'.
381
+ */
382
+ context?: Record<string, unknown>;
383
+ /**
384
+ * Execution timeout in milliseconds.
385
+ * Set to 0 to disable timeout.
386
+ * @default 30000
387
+ */
388
+ timeout?: number;
389
+ }
390
+ /**
391
+ * Result of running code in the sandbox.
392
+ *
393
+ * Extends ExecuteResult with build failure information.
394
+ * If `buildFailure` is present, the build failed before execution.
395
+ */
396
+ export interface RunResult extends ExecuteResult {
397
+ /** If build failed, contains failure details (same structure as BuildFailure) */
398
+ buildFailure?: BuildFailureDetails;
399
+ }
400
+ export interface Sandbox {
401
+ /**
402
+ * The virtual filesystem (sync)
403
+ */
404
+ readonly fs: Filesystem;
405
+ /**
406
+ * Execute a shell command
407
+ */
408
+ exec(command: string): Promise<ExecResult>;
409
+ /**
410
+ * The last successful build result (code string + metadata)
411
+ */
412
+ readonly lastBuild: BuildSuccess | null;
413
+ /**
414
+ * Get the current sandbox state for persistence
415
+ */
416
+ getState(): SandboxState;
417
+ /**
418
+ * Read a file from the virtual filesystem.
419
+ *
420
+ * @param path - Absolute path to the file (e.g., "/src/app.ts")
421
+ * @returns File contents as a string
422
+ * @throws If the file does not exist
423
+ */
424
+ readFile(path: string): string;
425
+ /**
426
+ * Write a file to the virtual filesystem.
427
+ * Creates parent directories automatically if they don't exist.
428
+ *
429
+ * @param path - Absolute path to the file (e.g., "/src/app.ts")
430
+ * @param content - File contents to write
431
+ */
432
+ writeFile(path: string, content: string): void;
433
+ /**
434
+ * Subscribe to build events
435
+ */
436
+ onBuild(callback: (result: BuildSuccess) => void | Promise<void>): () => void;
437
+ /**
438
+ * Install a package from npm.
439
+ * Updates /package.json and fetches type definitions if typesResolver is configured.
440
+ *
441
+ * @param packageSpec - Package specifier (e.g., "lodash", "lodash@4.17.21", "@types/node@20")
442
+ * @returns Installation result with version and types info
443
+ *
444
+ * @example
445
+ * await sandbox.install("lodash@4.17.21");
446
+ * await sandbox.install("@tanstack/react-query");
447
+ */
448
+ install(packageSpec: string): Promise<InstallResult>;
449
+ /**
450
+ * Uninstall a package.
451
+ * Removes from /package.json and deletes type definition files.
452
+ *
453
+ * @param packageName - Package name (e.g., "lodash", "@tanstack/react-query")
454
+ * @returns Whether the package was removed
455
+ */
456
+ uninstall(packageName: string): Promise<UninstallResult>;
457
+ /**
458
+ * Build the project.
459
+ * Reads dependencies from /package.json, optionally typechecks, and bundles.
460
+ * Returns the bundled code string (does NOT execute it).
461
+ *
462
+ * @param options - Build options
463
+ * @returns Build result - check `success` field to determine outcome
464
+ */
465
+ build(options?: SandboxBuildOptions): Promise<BuildResult>;
466
+ /**
467
+ * Type check the project.
468
+ * Reads tsconfig from filesystem and runs the typechecker.
469
+ *
470
+ * @param options - Typecheck options
471
+ * @returns Typecheck result with diagnostics
472
+ */
473
+ typecheck(options?: SandboxTypecheckOptions): Promise<TypecheckResult>;
474
+ /**
475
+ * Build and run code using the configured executor.
476
+ *
477
+ * This is a convenience method that:
478
+ * 1. Builds the code (typecheck + bundle)
479
+ * 2. Passes the bundled code to the executor
480
+ * 3. Returns the execution result
481
+ *
482
+ * Requires an executor to be configured when creating Sandlot.
483
+ *
484
+ * @param options - Run options (entry point, context, timeout, etc.)
485
+ * @returns Run result with logs, return value, and any error
486
+ * @throws If no executor was configured
487
+ *
488
+ * @example
489
+ * ```ts
490
+ * // Script style - top-level code runs on import
491
+ * sandbox.writeFile('/index.ts', 'console.log("Hello!")');
492
+ * const result = await sandbox.run();
493
+ * console.log(result.logs); // ['Hello!']
494
+ *
495
+ * // Main function style - gets context
496
+ * sandbox.writeFile('/index.ts', `
497
+ * export function main(ctx) {
498
+ * ctx.log("Args:", ctx.args);
499
+ * return { success: true };
500
+ * }
501
+ * `);
502
+ * const result = await sandbox.run({
503
+ * context: { args: ['--verbose'] }
504
+ * });
505
+ * console.log(result.returnValue); // { success: true }
506
+ * ```
507
+ */
508
+ run(options?: RunOptions): Promise<RunResult>;
509
+ }
510
+ export interface ExecResult {
511
+ exitCode: number;
512
+ stdout: string;
513
+ stderr: string;
514
+ }
515
+ export interface SandboxState {
516
+ files: Record<string, string>;
517
+ }
518
+ export interface Sandlot {
519
+ /**
520
+ * Create a new sandbox environment
521
+ */
522
+ createSandbox(options?: SandboxOptions): Promise<Sandbox>;
523
+ /**
524
+ * The shared module registry (if shared modules were provided)
525
+ */
526
+ readonly sharedModules: ISharedModuleRegistry | null;
527
+ }
528
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,8 +1,13 @@
1
1
  {
2
2
  "name": "sandlot",
3
- "version": "0.1.4",
3
+ "version": "0.2.1",
4
4
  "description": "TypeScript sandbox with esbuild bundling and type checking for browser and server",
5
5
  "author": "blindmansion",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/blindmansion/sandlot.git",
9
+ "directory": "packages/sandlot"
10
+ },
6
11
  "license": "MIT",
7
12
  "keywords": [
8
13
  "sandbox",
@@ -22,10 +27,15 @@
22
27
  "import": "./dist/index.js",
23
28
  "default": "./dist/index.js"
24
29
  },
25
- "./internal": {
26
- "types": "./dist/internal.d.ts",
27
- "import": "./dist/internal.js",
28
- "default": "./dist/internal.js"
30
+ "./browser": {
31
+ "types": "./dist/browser/index.d.ts",
32
+ "import": "./dist/browser/index.js",
33
+ "default": "./dist/browser/index.js"
34
+ },
35
+ "./node": {
36
+ "types": "./dist/node/index.d.ts",
37
+ "import": "./dist/node/index.js",
38
+ "default": "./dist/node/index.js"
29
39
  }
30
40
  },
31
41
  "files": [
@@ -34,7 +44,7 @@
34
44
  ],
35
45
  "scripts": {
36
46
  "build": "bun run build:js && bun run build:types",
37
- "build:js": "bun build ./src/index.ts ./src/internal.ts --outdir ./dist --format esm --packages external",
47
+ "build:js": "bun build ./src/index.ts ./src/browser/index.ts ./src/node/index.ts --outdir ./dist --format esm --packages external",
38
48
  "build:types": "tsc --emitDeclarationOnly",
39
49
  "prepublishOnly": "bun run build"
40
50
  },