bun-types 1.3.2-canary.20251104T140728 → 1.3.2-canary.20251106T140813

package/docs/api/secrets.md

@@ -1,319 +0,0 @@
-Store and retrieve sensitive credentials securely using the operating system's native credential storage APIs.
-
-**Experimental:** This API is new and experimental. It may change in the future.
-
-```typescript
-import { secrets } from "bun";
-
-const githubToken = await secrets.get({
-  service: "my-cli-tool",
-  name: "github-token",
-});
-
-if (!githubToken) {
-  const response = await fetch("https://api.github.com/name", {
-    headers: { "Authorization": `token ${githubToken}` },
-  });
-  console.log("Please enter your GitHub token");
-} else {
-  await secrets.set({
-    service: "my-cli-tool",
-    name: "github-token",
-    value: prompt("Please enter your GitHub token"),
-  });
-  console.log("GitHub token stored");
-}
-```
-
-## Overview
-
-`Bun.secrets` provides a cross-platform API for managing sensitive credentials that CLI tools and development applications typically store in plaintext files like `~/.npmrc`, `~/.aws/credentials`, or `.env` files. It uses:
-
-- **macOS**: Keychain Services
-- **Linux**: libsecret (GNOME Keyring, KWallet, etc.)
-- **Windows**: Windows Credential Manager
-
-All operations are asynchronous and non-blocking, running on Bun's threadpool.
-
-Note: in the future, we may add an additional `provider` option to make this better for production deployment secrets, but today this API is mostly useful for local development tools.
-
-## API
-
-### `Bun.secrets.get(options)`
-
-Retrieve a stored credential.
-
-```typescript
-import { secrets } from "bun";
-
-const password = await Bun.secrets.get({
-  service: "my-app",
-  name: "alice@example.com",
-});
-// Returns: string | null
-
-// Or if you prefer without an object
-const password = await Bun.secrets.get("my-app", "alice@example.com");
-```
-
-**Parameters:**
-
-- `options.service` (string, required) - The service or application name
-- `options.name` (string, required) - The username or account identifier
-
-**Returns:**
-
-- `Promise<string | null>` - The stored password, or `null` if not found
-
-### `Bun.secrets.set(options, value)`
-
-Store or update a credential.
-
-```typescript
-import { secrets } from "bun";
-
-await secrets.set({
-  service: "my-app",
-  name: "alice@example.com",
-  value: "super-secret-password",
-});
-```
-
-**Parameters:**
-
-- `options.service` (string, required) - The service or application name
-- `options.name` (string, required) - The username or account identifier
-- `value` (string, required) - The password or secret to store
-
-**Notes:**
-
-- If a credential already exists for the given service/name combination, it will be replaced
-- The stored value is encrypted by the operating system
-
-### `Bun.secrets.delete(options)`
-
-Delete a stored credential.
-
-```typescript
-const deleted = await Bun.secrets.delete({
-  service: "my-app",
-  name: "alice@example.com",
-  value: "super-secret-password",
-});
-// Returns: boolean
-```
-
-**Parameters:**
-
-- `options.service` (string, required) - The service or application name
-- `options.name` (string, required) - The username or account identifier
-
-**Returns:**
-
-- `Promise<boolean>` - `true` if a credential was deleted, `false` if not found
-
-## Examples
-
-### Storing CLI Tool Credentials
-
-```javascript
-// Store GitHub CLI token (instead of ~/.config/gh/hosts.yml)
-await Bun.secrets.set({
-  service: "my-app.com",
-  name: "github-token",
-  value: "ghp_xxxxxxxxxxxxxxxxxxxx",
-});
-
-// Or if you prefer without an object
-await Bun.secrets.set("my-app.com", "github-token", "ghp_xxxxxxxxxxxxxxxxxxxx");
-
-// Store npm registry token (instead of ~/.npmrc)
-await Bun.secrets.set({
-  service: "npm-registry",
-  name: "https://registry.npmjs.org",
-  value: "npm_xxxxxxxxxxxxxxxxxxxx",
-});
-
-// Retrieve for API calls
-const token = await Bun.secrets.get({
-  service: "gh-cli",
-  name: "github.com",
-});
-
-if (token) {
-  const response = await fetch("https://api.github.com/name", {
-    headers: {
-      "Authorization": `token ${token}`,
-    },
-  });
-}
-```
-
-### Migrating from Plaintext Config Files
-
-```javascript
-// Instead of storing in ~/.aws/credentials
-await Bun.secrets.set({
-  service: "aws-cli",
-  name: "AWS_SECRET_ACCESS_KEY",
-  value: process.env.AWS_SECRET_ACCESS_KEY,
-});
-
-// Instead of .env files with sensitive data
-await Bun.secrets.set({
-  service: "my-app",
-  name: "api-key",
-  value: "sk_live_xxxxxxxxxxxxxxxxxxxx",
-});
-
-// Load at runtime
-const apiKey =
-  (await Bun.secrets.get({
-    service: "my-app",
-    name: "api-key",
-  })) || process.env.API_KEY; // Fallback for CI/production
-```
-
-### Error Handling
-
-```javascript
-try {
-  await Bun.secrets.set({
-    service: "my-app",
-    name: "alice",
-    value: "password123",
-  });
-} catch (error) {
-  console.error("Failed to store credential:", error.message);
-}
-
-// Check if a credential exists
-const password = await Bun.secrets.get({
-  service: "my-app",
-  name: "alice",
-});
-
-if (password === null) {
-  console.log("No credential found");
-}
-```
-
-### Updating Credentials
-
-```javascript
-// Initial password
-await Bun.secrets.set({
-  service: "email-server",
-  name: "admin@example.com",
-  value: "old-password",
-});
-
-// Update to new password
-await Bun.secrets.set({
-  service: "email-server",
-  name: "admin@example.com",
-  value: "new-password",
-});
-
-// The old password is replaced
-```
-
-## Platform Behavior
-
-### macOS (Keychain)
-
-- Credentials are stored in the name's login keychain
-- The keychain may prompt for access permission on first use
-- Credentials persist across system restarts
-- Accessible by the name who stored them
-
-### Linux (libsecret)
-
-- Requires a secret service daemon (GNOME Keyring, KWallet, etc.)
-- Credentials are stored in the default collection
-- May prompt for unlock if the keyring is locked
-- The secret service must be running
-
-### Windows (Credential Manager)
-
-- Credentials are stored in Windows Credential Manager
-- Visible in Control Panel → Credential Manager → Windows Credentials
-- Persist with `CRED_PERSIST_ENTERPRISE` flag so it's scoped per user
-- Encrypted using Windows Data Protection API
-
-## Security Considerations
-
-1. **Encryption**: Credentials are encrypted by the operating system's credential manager
-2. **Access Control**: Only the name who stored the credential can retrieve it
-3. **No Plain Text**: Passwords are never stored in plain text
-4. **Memory Safety**: Bun zeros out password memory after use
-5. **Process Isolation**: Credentials are isolated per name account
-
-## Limitations
-
-- Maximum password length varies by platform (typically 2048-4096 bytes)
-- Service and name names should be reasonable lengths (< 256 characters)
-- Some special characters may need escaping depending on the platform
-- Requires appropriate system services:
-  - Linux: Secret service daemon must be running
-  - macOS: Keychain Access must be available
-  - Windows: Credential Manager service must be enabled
-
-## Comparison with Environment Variables
-
-Unlike environment variables, `Bun.secrets`:
-
-- ✅ Encrypts credentials at rest (thanks to the operating system)
-- ✅ Avoids exposing secrets in process memory dumps (memory is zeroed after its no longer needed)
-- ✅ Survives application restarts
-- ✅ Can be updated without restarting the application
-- ✅ Provides name-level access control
-- ❌ Requires OS credential service
-- ❌ Not very useful for deployment secrets (use environment variables in production)
-
-## Best Practices
-
-1. **Use descriptive service names**: Match the tool or application name
-   If you're building a CLI for external use, you probably should use a UTI (Uniform Type Identifier) for the service name.
-
-   ```javascript
-   // Good - matches the actual tool
-   { service: "com.docker.hub", name: "username" }
-   { service: "com.vercel.cli", name: "team-name" }
-
-   // Avoid - too generic
-   { service: "api", name: "key" }
-   ```
-
-2. **Credentials-only**: Don't store application configuration in this API
-   This API is slow, you probably still need to use a config file for some things.
-
-3. **Use for local development tools**:
-   - ✅ CLI tools (gh, npm, docker, kubectl)
-   - ✅ Local development servers
-   - ✅ Personal API keys for testing
-   - ❌ Production servers (use proper secret management)
-
-## TypeScript
-
-```typescript
-namespace Bun {
-  interface SecretsOptions {
-    service: string;
-    name: string;
-  }
-
-  interface Secrets {
-    get(options: SecretsOptions): Promise<string | null>;
-    set(options: SecretsOptions, value: string): Promise<void>;
-    delete(options: SecretsOptions): Promise<boolean>;
-  }
-
-  const secrets: Secrets;
-}
-```
-
-## See Also
-
-- [Environment Variables](./env.md) - For deployment configuration
-- [Bun.password](./password.md) - For password hashing and verification

package/docs/api/semver.md

@@ -1,52 +0,0 @@
-Bun implements a semantic versioning API which can be used to compare versions and determine if a version is compatible with another range of versions. The versions and ranges are designed to be compatible with `node-semver`, which is used by npm clients.
-
-It's about 20x faster than `node-semver`.
-
-![Benchmark](https://github.com/oven-sh/bun/assets/709451/94746adc-8aba-4baf-a143-3c355f8e0f78)
-
-Currently, this API provides two functions :
-
-#### `Bun.semver.satisfies(version: string, range: string): boolean`
-
-Returns `true` if `version` satisfies `range`, otherwise `false`.
-
-Example:
-
-```typescript
-import { semver } from "bun";
-
-semver.satisfies("1.0.0", "^1.0.0"); // true
-semver.satisfies("1.0.0", "^1.0.1"); // false
-semver.satisfies("1.0.0", "~1.0.0"); // true
-semver.satisfies("1.0.0", "~1.0.1"); // false
-semver.satisfies("1.0.0", "1.0.0"); // true
-semver.satisfies("1.0.0", "1.0.1"); // false
-semver.satisfies("1.0.1", "1.0.0"); // false
-semver.satisfies("1.0.0", "1.0.x"); // true
-semver.satisfies("1.0.0", "1.x.x"); // true
-semver.satisfies("1.0.0", "x.x.x"); // true
-semver.satisfies("1.0.0", "1.0.0 - 2.0.0"); // true
-semver.satisfies("1.0.0", "1.0.0 - 1.0.1"); // true
-```
-
-If `range` is invalid, it returns false. If `version` is invalid, it returns false.
-
-#### `Bun.semver.order(versionA: string, versionB: string): 0 | 1 | -1`
-
-Returns `0` if `versionA` and `versionB` are equal, `1` if `versionA` is greater than `versionB`, and `-1` if `versionA` is less than `versionB`.
-
-Example:
-
-```typescript
-import { semver } from "bun";
-
-semver.order("1.0.0", "1.0.0"); // 0
-semver.order("1.0.0", "1.0.1"); // -1
-semver.order("1.0.1", "1.0.0"); // 1
-
-const unsorted = ["1.0.0", "1.0.1", "1.0.0-alpha", "1.0.0-beta", "1.0.0-rc"];
-unsorted.sort(semver.order); // ["1.0.0-alpha", "1.0.0-beta", "1.0.0-rc", "1.0.0", "1.0.1"]
-console.log(unsorted);
-```
-
-If you need other semver functions, feel free to open an issue or pull request.