mirror of
https://github.com/oven-sh/bun
synced 2026-02-13 20:39:05 +00:00
docs: remove internal APIs that should not be publicly documented
Remove documentation for internal/private APIs: - Bun.createParsedShellScript() from runtime/shell.md - Bun.createShellInterpreter() from runtime/shell.md - Bun.shrink() from api/utils.md - Bun.registerMacro() from bundler/macros.md These APIs are internal implementation details and should not be part of the public documentation. Only user-facing APIs should be documented. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude Bot
@@ -1033,67 +1033,6 @@ console.log(`Unsafe allocation: ${unsafeTime} ns`);
|
||||
// Unsafe is typically 2-10x faster for large allocations
|
||||
```
|
||||
|
||||
## `Bun.shrink()`
|
||||
|
||||
`Bun.shrink(object: object): object`
|
||||
|
||||
Optimizes the memory layout of an object by shrinking its internal representation. This is most effective after adding and removing many properties, which can leave gaps in the object's property storage.
|
||||
|
||||
```ts
|
||||
const obj = { a: 1, b: 2, c: 3, d: 4, e: 5 };
|
||||
|
||||
// Add and remove many properties (creates fragmentation)
|
||||
for (let i = 0; i < 1000; i++) {
|
||||
obj[`temp${i}`] = i;
|
||||
}
|
||||
|
||||
for (let i = 0; i < 1000; i++) {
|
||||
delete obj[`temp${i}`];
|
||||
}
|
||||
|
||||
// Object now has fragmented memory layout
|
||||
console.log(Object.keys(obj)); // => ["a", "b", "c", "d", "e"]
|
||||
|
||||
// Optimize memory layout
|
||||
Bun.shrink(obj);
|
||||
// Returns the same object, but with optimized internal structure
|
||||
```
|
||||
|
||||
Useful for long-lived objects that undergo many property changes:
|
||||
|
||||
```ts
|
||||
class Cache {
|
||||
private data = {};
|
||||
|
||||
set(key: string, value: any) {
|
||||
this.data[key] = value;
|
||||
}
|
||||
|
||||
delete(key: string) {
|
||||
delete this.data[key];
|
||||
}
|
||||
|
||||
// Optimize after batch operations
|
||||
optimize() {
|
||||
return Bun.shrink(this.data);
|
||||
}
|
||||
}
|
||||
|
||||
const cache = new Cache();
|
||||
// ... many set/delete operations
|
||||
cache.optimize(); // Reclaim fragmented memory
|
||||
```
|
||||
|
||||
The function returns the same object (doesn't create a copy):
|
||||
|
||||
```ts
|
||||
const original = { foo: "bar" };
|
||||
const shrunk = Bun.shrink(original);
|
||||
console.log(original === shrunk); // => true
|
||||
```
|
||||
|
||||
**Note**: This is a performance optimization hint. The JavaScript engine may ignore it if the object is already optimally laid out or if shrinking wouldn't provide benefits.
|
||||
|
||||
## `Bun.gc()`
|
||||
|
||||
`Bun.gc(force?: boolean): void`
|
||||
|
||||
@@ -328,30 +328,3 @@ export { Head };
|
||||
|
||||
{% /codetabs %}
|
||||
|
||||
## Advanced Macro APIs
|
||||
|
||||
### `Bun.registerMacro(id, macro)`
|
||||
|
||||
Registers a macro function with a specific numeric ID for internal use by the bundler. This is a low-level API primarily used internally during the bundling process.
|
||||
|
||||
```js
|
||||
// This API is primarily used internally by the bundler
|
||||
// Most users should use import statements with { type: "macro" } instead
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `id` (`number`): A unique numeric identifier for the macro (must be positive, non-zero)
|
||||
- `macro` (`Function`): The macro function to register
|
||||
|
||||
**Returns:** `undefined`
|
||||
|
||||
{% callout type="warning" %}
|
||||
**Note** — `Bun.registerMacro()` is an internal API used by Bun's bundler during code generation. User code should not call this function directly. Instead, use the standard `import { myMacro } from "./macro.ts" with { type: "macro" }` syntax to define and use macros.
|
||||
{% /callout %}
|
||||
|
||||
**Security considerations:**
|
||||
- Only callable functions are accepted as macro arguments
|
||||
- Invalid IDs (0, -1, or non-numeric values) will throw an error
|
||||
- This function requires exactly 2 arguments
|
||||
|
||||
The bundler automatically calls `registerMacro()` when it encounters macro imports during the bundling process, assigning unique IDs to each macro and registering them for execution.
|
||||
|
||||
@@ -600,60 +600,6 @@ user-provided input before passing it as an argument to an external command.
|
||||
The responsibility for validating arguments rests with your application code.
|
||||
{% /callout %}
|
||||
|
||||
## Advanced APIs
|
||||
|
||||
### `Bun.createParsedShellScript(script, args)`
|
||||
|
||||
Creates a pre-parsed shell script object that can be used with `Bun.createShellInterpreter()` for more advanced shell execution control.
|
||||
|
||||
```js
|
||||
import { createParsedShellScript } from "bun";
|
||||
|
||||
// Parse a shell script
|
||||
const parsed = createParsedShellScript("echo hello", ["world"]);
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `script` (`string`): The shell script string to parse
|
||||
- `args` (`string[]`): Array of arguments to interpolate into the script
|
||||
|
||||
**Returns:** `ParsedShellScript` - A parsed shell script object
|
||||
|
||||
This API is primarily used internally by the `$` template literal, but can be useful for cases where you want to pre-parse shell commands or build custom shell execution workflows.
|
||||
|
||||
### `Bun.createShellInterpreter(options)`
|
||||
|
||||
Creates a shell interpreter instance for executing parsed shell scripts with custom resolve/reject handlers.
|
||||
|
||||
```js
|
||||
import { createParsedShellScript, createShellInterpreter } from "bun";
|
||||
|
||||
const parsed = createParsedShellScript("echo hello", ["world"]);
|
||||
|
||||
const interpreter = createShellInterpreter(
|
||||
(exitCode, stdout, stderr) => {
|
||||
// Handle successful completion
|
||||
console.log(`Exit code: ${exitCode}`);
|
||||
console.log(`Stdout: ${stdout.toString()}`);
|
||||
},
|
||||
(exitCode, stdout, stderr) => {
|
||||
// Handle errors
|
||||
console.error(`Command failed with code: ${exitCode}`);
|
||||
console.error(`Stderr: ${stderr.toString()}`);
|
||||
},
|
||||
parsed
|
||||
);
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `resolve` (`(exitCode: number, stdout: Buffer, stderr: Buffer) => void`): Callback for successful execution
|
||||
- `reject` (`(exitCode: number, stdout: Buffer, stderr: Buffer) => void`): Callback for failed execution
|
||||
- `parsedScript` (`ParsedShellScript`): The parsed shell script to execute
|
||||
|
||||
**Returns:** `ShellInterpreter` - A shell interpreter instance
|
||||
|
||||
This low-level API gives you direct control over shell execution and is primarily used internally by Bun Shell. Most users should use the `$` template literal instead, which provides a higher-level interface.
|
||||
|
||||
## Credits
|
||||
|
||||
Large parts of this API were inspired by [zx](https://github.com/google/zx), [dax](https://github.com/dsherret/dax), and [bnx](https://github.com/wobsoriano/bnx). Thank you to the authors of those projects.
|
||||
|
||||
Reference in New Issue
Block a user