@hasna/skills 0.1.20 → 0.1.22

package/skills/skill-logo-design/node_modules/bun-types/docs/runtime/index.mdx

@@ -0,0 +1,223 @@
+---
+title: Bun Runtime
+description: Execute JavaScript/TypeScript files, package.json scripts, and executable packages with Bun's fast runtime.
+---
+
+import Run from "/snippets/cli/run.mdx";
+
+The Bun Runtime is designed to start fast and run fast.
+
+Under the hood, Bun uses the [JavaScriptCore engine](https://developer.apple.com/documentation/javascriptcore), which is developed by Apple for Safari. In most cases, the startup and running performance is faster than V8, the engine used by Node.js and Chromium-based browsers. Its transpiler and runtime are written in Zig, a modern, high-performance language. On Linux, this translates into startup times [4x faster](https://twitter.com/jarredsumner/status/1499225725492076544) than Node.js.
+
+| Command         | Time     |
+| --------------- | -------- |
+| `bun hello.js`  | `5.2ms`  |
+| `node hello.js` | `25.1ms` |
+
+This benchmark is based on running a simple Hello World script on Linux
+
+## Run a file
+
+Use `bun run` to execute a source file.
+
+```bash terminal icon="terminal"
+bun run index.js
+```
+
+Bun supports TypeScript and JSX out of the box. Every file is transpiled on the fly by Bun's fast native transpiler before being executed.
+
+```bash terminal icon="terminal"
+bun run index.js
+bun run index.jsx
+bun run index.ts
+bun run index.tsx
+```
+
+Alternatively, you can omit the `run` keyword and use the "naked" command; it behaves identically.
+
+```bash terminal icon="terminal"
+bun index.tsx
+bun index.js
+```
+
+### `--watch`
+
+To run a file in watch mode, use the `--watch` flag.
+
+```bash terminal icon="terminal"
+bun --watch run index.tsx
+```
+
+<Note>
+When using `bun run`, put Bun flags like `--watch` immediately after `bun`.
+
+```bash
+bun --watch run dev # ✔️ do this
+bun run dev --watch # ❌ don't do this
+```
+
+Flags that occur at the end of the command will be ignored and passed through to the `"dev"` script itself.
+
+</Note>
+
+## Run a `package.json` script
+
+<Note>
+Compare to `npm run <script>` or `yarn <script>`
+</Note>
+
+```sh
+bun [bun flags] run <script> [script flags]
+```
+
+Your `package.json` can define a number of named `"scripts"` that correspond to shell commands.
+
+```json package.json icon="file-json"
+{
+  // ... other fields
+  "scripts": {
+    "clean": "rm -rf dist && echo 'Done.'",
+    "dev": "bun server.ts"
+  }
+}
+```
+
+Use `bun run <script>` to execute these scripts.
+
+```bash terminal icon="terminal"
+bun run clean
+rm -rf dist && echo 'Done.'
+```
+
+```txt
+Cleaning...
+Done.
+```
+
+Bun executes the script command in a subshell. On Linux & macOS, it checks for the following shells in order, using the first one it finds: `bash`, `sh`, `zsh`. On Windows, it uses [bun shell](/docs/runtime/shell) to support bash-like syntax and many common commands.
+
+<Note>⚡️ The startup time for `npm run` on Linux is roughly 170ms; with Bun it is `6ms`.</Note>
+
+Scripts can also be run with the shorter command `bun <script>`, however if there is a built-in bun command with the same name, the built-in command takes precedence. In this case, use the more explicit `bun run <script>` command to execute your package script.
+
+```bash terminal icon="terminal"
+bun run dev
+```
+
+To see a list of available scripts, run `bun run` without any arguments.
+
+```bash terminal icon="terminal"
+bun run
+```
+
+```txt
+quickstart scripts:
+
+ bun run clean
+   rm -rf dist && echo 'Done.'
+
+ bun run dev
+   bun server.ts
+
+2 scripts
+```
+
+Bun respects lifecycle hooks. For instance, `bun run clean` will execute `preclean` and `postclean`, if defined. If the `pre<script>` fails, Bun will not execute the script itself.
+
+### `--bun`
+
+It's common for `package.json` scripts to reference locally-installed CLIs like `vite` or `next`. These CLIs are often JavaScript files marked with a [shebang](<https://en.wikipedia.org/wiki/Shebang_(Unix)>) to indicate that they should be executed with `node`.
+
+```js cli.js icon="/icons/javascript.svg"
+#!/usr/bin/env node
+
+// do stuff
+```
+
+By default, Bun respects this shebang and executes the script with `node`. However, you can override this behavior with the `--bun` flag. For Node.js-based CLIs, this will run the CLI with Bun instead of Node.js.
+
+```bash terminal icon="terminal"
+bun run --bun vite
+```
+
+### Filtering
+
+In monorepos containing multiple packages, you can use the `--filter` argument to execute scripts in many packages at once.
+
+Use `bun run --filter <name_pattern> <script>` to execute `<script>` in all packages whose name matches `<name_pattern>`.
+For example, if you have subdirectories containing packages named `foo`, `bar` and `baz`, running
+
+```bash terminal icon="terminal"
+bun run --filter 'ba*' <script>
+```
+
+will execute `<script>` in both `bar` and `baz`, but not in `foo`.
+
+Find more details in the docs page for [filter](/docs/pm/filter#running-scripts-with-filter).
+
+## `bun run -` to pipe code from stdin
+
+`bun run -` lets you read JavaScript, TypeScript, TSX, or JSX from stdin and execute it without writing to a temporary file first.
+
+```bash terminal icon="terminal"
+echo "console.log('Hello')" | bun run -
+```
+
+```txt
+Hello
+```
+
+You can also use `bun run -` to redirect files into Bun. For example, to run a `.js` file as if it were a `.ts` file:
+
+```bash terminal icon="terminal"
+echo "console.log!('This is TypeScript!' as any)" > secretly-typescript.js
+bun run - < secretly-typescript.js
+```
+
+```txt
+This is TypeScript!
+```
+
+For convenience, all code is treated as TypeScript with JSX support when using `bun run -`.
+
+## `bun run --console-depth`
+
+Control the depth of object inspection in console output with the `--console-depth` flag.
+
+```bash terminal icon="terminal"
+bun --console-depth 5 run index.tsx
+```
+
+This sets how deeply nested objects are displayed in `console.log()` output. The default depth is `2`. Higher values show more nested properties but may produce verbose output for complex objects.
+
+```ts console.ts icon="/icons/typescript.svg"
+const nested = { a: { b: { c: { d: "deep" } } } };
+console.log(nested);
+// With --console-depth 2 (default): { a: { b: [Object] } }
+// With --console-depth 4: { a: { b: { c: { d: 'deep' } } } }
+```
+
+## `bun run --smol`
+
+In memory-constrained environments, use the `--smol` flag to reduce memory usage at a cost to performance.
+
+```bash terminal icon="terminal"
+bun --smol run index.tsx
+```
+
+This causes the garbage collector to run more frequently, which can slow down execution. However, it can be useful in environments with limited memory. Bun automatically adjusts the garbage collector's heap size based on the available memory (accounting for cgroups and other memory limits) with and without the `--smol` flag, so this is mostly useful for cases where you want to make the heap size grow more slowly.
+
+## Resolution order
+
+Absolute paths and paths starting with `./` or `.\\` are always executed as source files. Unless using `bun run`, running a file with an allowed extension will prefer the file over a package.json script.
+
+When there is a package.json script and a file with the same name, `bun run` prioritizes the package.json script. The full resolution order is:
+
+1. package.json scripts, eg `bun run build`
+2. Source files, eg `bun run src/main.js`
+3. Binaries from project packages, eg `bun add eslint && bun run eslint`
+4. (`bun run` only) System commands, eg `bun run ls`
+
+---
+
+<Run />

package/skills/skill-logo-design/node_modules/bun-types/docs/runtime/json5.mdx

@@ -0,0 +1,271 @@
+---
+title: JSON5
+description: Use Bun's built-in support for JSON5 files through both runtime APIs and bundler integration
+---
+
+In Bun, JSON5 is a first-class citizen alongside JSON, TOML, and YAML. You can:
+
+- Parse and stringify JSON5 with `Bun.JSON5.parse` and `Bun.JSON5.stringify`
+- `import` & `require` JSON5 files as modules at runtime (including hot reloading & watch mode support)
+- `import` & `require` JSON5 files in frontend apps via Bun's bundler
+
+---
+
+## Conformance
+
+Bun's JSON5 parser passes 100% of the [official JSON5 test suite](https://github.com/json5/json5-tests). The parser is written in Zig for optimal performance. You can view our [translated test suite](https://github.com/oven-sh/bun/blob/main/test/js/bun/json5/json5-test-suite.test.ts) to see every test case.
+
+---
+
+## Runtime API
+
+### `Bun.JSON5.parse()`
+
+Parse a JSON5 string into a JavaScript value.
+
+```ts
+import { JSON5 } from "bun";
+
+const data = JSON5.parse(`{
+  // JSON5 supports comments
+  name: 'my-app',
+  version: '1.0.0',
+  debug: true,
+
+  // trailing commas are allowed
+  tags: ['web', 'api',],
+}`);
+
+console.log(data);
+// {
+//   name: "my-app",
+//   version: "1.0.0",
+//   debug: true,
+//   tags: ["web", "api"]
+// }
+```
+
+#### Supported JSON5 Features
+
+JSON5 is a superset of JSON based on ECMAScript 5.1 syntax. It supports:
+
+- **Comments**: single-line (`//`) and multi-line (`/* */`)
+- **Trailing commas**: in objects and arrays
+- **Unquoted keys**: valid ECMAScript 5.1 identifiers can be used as keys
+- **Single-quoted strings**: in addition to double-quoted strings
+- **Multi-line strings**: using backslash line continuations
+- **Hex numbers**: `0xFF`
+- **Leading & trailing decimal points**: `.5` and `5.`
+- **Infinity and NaN**: positive and negative
+- **Explicit plus sign**: `+42`
+
+```ts
+const data = JSON5.parse(`{
+  // Unquoted keys
+  unquoted: 'keys work',
+
+  // Single and double quotes
+  single: 'single-quoted',
+  double: "double-quoted",
+
+  // Trailing commas
+  trailing: 'comma',
+
+  // Special numbers
+  hex: 0xDEADbeef,
+  half: .5,
+  to: Infinity,
+  nan: NaN,
+
+  // Multi-line strings
+  multiline: 'line 1 \
+line 2',
+}`);
+```
+
+#### Error Handling
+
+`Bun.JSON5.parse()` throws a `SyntaxError` if the input is invalid JSON5:
+
+```ts
+try {
+  JSON5.parse("{invalid}");
+} catch (error) {
+  console.error("Failed to parse JSON5:", error.message);
+}
+```
+
+### `Bun.JSON5.stringify()`
+
+Stringify a JavaScript value to a JSON5 string.
+
+```ts
+import { JSON5 } from "bun";
+
+const str = JSON5.stringify({ name: "my-app", version: "1.0.0" });
+console.log(str);
+// {name:'my-app',version:'1.0.0'}
+```
+
+#### Pretty Printing
+
+Pass a `space` argument to format the output with indentation:
+
+```ts
+const pretty = JSON5.stringify(
+  {
+    name: "my-app",
+    debug: true,
+    tags: ["web", "api"],
+  },
+  null,
+  2,
+);
+
+console.log(pretty);
+// {
+//   name: 'my-app',
+//   debug: true,
+//   tags: [
+//     'web',
+//     'api',
+//   ],
+// }
+```
+
+The `space` argument can be a number (number of spaces) or a string (used as the indent character):
+
+```ts
+// Tab indentation
+JSON5.stringify(data, null, "\t");
+```
+
+#### Special Values
+
+Unlike `JSON.stringify`, `JSON5.stringify` preserves special numeric values:
+
+```ts
+JSON5.stringify({ inf: Infinity, ninf: -Infinity, nan: NaN });
+// {inf:Infinity,ninf:-Infinity,nan:NaN}
+```
+
+---
+
+## Module Import
+
+### ES Modules
+
+You can import JSON5 files directly as ES modules:
+
+```json5 config.json5
+{
+  // Database configuration
+  database: {
+    host: "localhost",
+    port: 5432,
+    name: "myapp",
+  },
+
+  features: {
+    auth: true,
+    rateLimit: true,
+    analytics: false,
+  },
+}
+```
+
+#### Default Import
+
+```ts app.ts icon="/icons/typescript.svg"
+import config from "./config.json5";
+
+console.log(config.database.host); // "localhost"
+console.log(config.features.auth); // true
+```
+
+#### Named Imports
+
+You can destructure top-level properties as named imports:
+
+```ts app.ts icon="/icons/typescript.svg"
+import { database, features } from "./config.json5";
+
+console.log(database.host); // "localhost"
+console.log(features.rateLimit); // true
+```
+
+### CommonJS
+
+JSON5 files can also be required in CommonJS:
+
+```ts app.ts icon="/icons/typescript.svg"
+const config = require("./config.json5");
+console.log(config.database.name); // "myapp"
+
+// Destructuring also works
+const { database, features } = require("./config.json5");
+```
+
+---
+
+## Hot Reloading with JSON5
+
+When you run your application with `bun --hot`, changes to JSON5 files are automatically detected and reloaded:
+
+```json5 config.json5
+{
+  server: {
+    port: 3000,
+    host: "localhost",
+  },
+  features: {
+    debug: true,
+    verbose: false,
+  },
+}
+```
+
+```ts server.ts icon="/icons/typescript.svg"
+import { server, features } from "./config.json5";
+
+Bun.serve({
+  port: server.port,
+  hostname: server.host,
+  fetch(req) {
+    if (features.verbose) {
+      console.log(`${req.method} ${req.url}`);
+    }
+    return new Response("Hello World");
+  },
+});
+```
+
+Run with hot reloading:
+
+```bash terminal icon="terminal"
+bun --hot server.ts
+```
+
+---
+
+## Bundler Integration
+
+When you import JSON5 files and bundle with Bun, the JSON5 is parsed at build time and included as a JavaScript module:
+
+```bash terminal icon="terminal"
+bun build app.ts --outdir=dist
+```
+
+This means:
+
+- Zero runtime JSON5 parsing overhead in production
+- Smaller bundle sizes
+- Tree-shaking support for unused properties (named imports)
+
+### Dynamic Imports
+
+JSON5 files can be dynamically imported:
+
+```ts
+const { default: config } = await import("./config.json5");
+```

package/skills/skill-logo-design/node_modules/bun-types/docs/runtime/jsonl.mdx

@@ -0,0 +1,188 @@
+---
+title: JSONL
+description: Parse newline-delimited JSON (JSONL) with Bun's built-in streaming parser
+---
+
+Bun has built-in support for parsing [JSONL](https://jsonlines.org/) (newline-delimited JSON), where each line is a separate JSON value. The parser is implemented in C++ using JavaScriptCore's optimized JSON parser and supports streaming use cases.
+
+```ts
+const results = Bun.JSONL.parse('{"name":"Alice"}\n{"name":"Bob"}\n');
+// [{ name: "Alice" }, { name: "Bob" }]
+```
+
+---
+
+## `Bun.JSONL.parse()`
+
+Parse a complete JSONL input and return an array of all parsed values.
+
+```ts
+import { JSONL } from "bun";
+
+const input = '{"id":1,"name":"Alice"}\n{"id":2,"name":"Bob"}\n{"id":3,"name":"Charlie"}\n';
+const records = JSONL.parse(input);
+console.log(records);
+// [
+//   { id: 1, name: "Alice" },
+//   { id: 2, name: "Bob" },
+//   { id: 3, name: "Charlie" }
+// ]
+```
+
+Input can be a string or a `Uint8Array`:
+
+```ts
+const buffer = new TextEncoder().encode('{"a":1}\n{"b":2}\n');
+const results = Bun.JSONL.parse(buffer);
+// [{ a: 1 }, { b: 2 }]
+```
+
+When passed a `Uint8Array`, a UTF-8 BOM at the start of the buffer is automatically skipped.
+
+### Error handling
+
+If the input contains invalid JSON, `Bun.JSONL.parse()` throws a `SyntaxError`:
+
+```ts
+try {
+  Bun.JSONL.parse('{"valid":true}\n{invalid}\n');
+} catch (error) {
+  console.error(error); // SyntaxError: Failed to parse JSONL
+}
+```
+
+---
+
+## `Bun.JSONL.parseChunk()`
+
+For streaming scenarios, `parseChunk` parses as many complete values as possible from the input and reports how far it got. This is useful when receiving data incrementally (e.g., from a network stream) and you need to know where to resume parsing.
+
+```ts
+const chunk = '{"id":1}\n{"id":2}\n{"id":3';
+
+const result = Bun.JSONL.parseChunk(chunk);
+console.log(result.values); // [{ id: 1 }, { id: 2 }]
+console.log(result.read); // 17 — characters consumed
+console.log(result.done); // false — incomplete value remains
+console.log(result.error); // null — no parse error
+```
+
+### Return value
+
+`parseChunk` returns an object with four properties:
+
+| Property | Type                  | Description                                                             |
+| -------- | --------------------- | ----------------------------------------------------------------------- |
+| `values` | `any[]`               | Array of successfully parsed JSON values                                |
+| `read`   | `number`              | Number of bytes (for `Uint8Array`) or characters (for strings) consumed |
+| `done`   | `boolean`             | `true` if the entire input was consumed with no remaining data          |
+| `error`  | `SyntaxError \| null` | Parse error, or `null` if no error occurred                             |
+
+### Streaming example
+
+Use `read` to slice off consumed input and carry forward the remainder:
+
+```ts
+let buffer = "";
+
+async function processStream(stream: ReadableStream<string>) {
+  for await (const chunk of stream) {
+    buffer += chunk;
+    const result = Bun.JSONL.parseChunk(buffer);
+
+    for (const value of result.values) {
+      handleRecord(value);
+    }
+
+    // Keep only the unconsumed portion
+    buffer = buffer.slice(result.read);
+  }
+
+  // Handle any remaining data
+  if (buffer.length > 0) {
+    const final = Bun.JSONL.parseChunk(buffer);
+    for (const value of final.values) {
+      handleRecord(value);
+    }
+    if (final.error) {
+      console.error("Parse error in final chunk:", final.error.message);
+    }
+  }
+}
+```
+
+### Byte offsets with `Uint8Array`
+
+When the input is a `Uint8Array`, you can pass optional `start` and `end` byte offsets:
+
+```ts
+const buf = new TextEncoder().encode('{"a":1}\n{"b":2}\n{"c":3}\n');
+
+// Parse starting from byte 8
+const result = Bun.JSONL.parseChunk(buf, 8);
+console.log(result.values); // [{ b: 2 }, { c: 3 }]
+console.log(result.read); // 24
+
+// Parse a specific range
+const partial = Bun.JSONL.parseChunk(buf, 0, 8);
+console.log(partial.values); // [{ a: 1 }]
+```
+
+The `read` value is always a byte offset into the original buffer, making it easy to use with `TypedArray.subarray()` for zero-copy streaming:
+
+```ts
+let buf = new Uint8Array(0);
+
+async function processBinaryStream(stream: ReadableStream<Uint8Array>) {
+  for await (const chunk of stream) {
+    // Append chunk to buffer
+    const newBuf = new Uint8Array(buf.length + chunk.length);
+    newBuf.set(buf);
+    newBuf.set(chunk, buf.length);
+    buf = newBuf;
+
+    const result = Bun.JSONL.parseChunk(buf);
+
+    for (const value of result.values) {
+      handleRecord(value);
+    }
+
+    // Keep unconsumed bytes
+    buf = buf.slice(result.read);
+  }
+}
+```
+
+### Error recovery
+
+Unlike `parse()`, `parseChunk()` does not throw on invalid JSON. Instead, it returns the error in the `error` property, along with any values that were successfully parsed before the error:
+
+```ts
+const input = '{"a":1}\n{invalid}\n{"b":2}\n';
+const result = Bun.JSONL.parseChunk(input);
+
+console.log(result.values); // [{ a: 1 }] — values parsed before the error
+console.log(result.error); // SyntaxError
+console.log(result.read); // 7 — position up to last successful parse
+```
+
+---
+
+## Supported value types
+
+Each line can be any valid JSON value, not just objects:
+
+```ts
+const input = '42\n"hello"\ntrue\nnull\n[1,2,3]\n{"key":"value"}\n';
+const values = Bun.JSONL.parse(input);
+// [42, "hello", true, null, [1, 2, 3], { key: "value" }]
+```
+
+---
+
+## Performance notes
+
+- **ASCII fast path**: Pure ASCII input is parsed directly without copying, using a zero-allocation `StringView`.
+- **UTF-8 support**: Non-ASCII `Uint8Array` input is decoded to UTF-16 using SIMD-accelerated conversion.
+- **BOM handling**: UTF-8 BOM (`0xEF 0xBB 0xBF`) at the start of a `Uint8Array` is automatically skipped.
+- **Pre-built object shape**: The result object from `parseChunk` uses a cached structure for fast property access.