### Quick Start: Build a basic URL with path and query parameters

Source: https://github.com/meabed/build-url-ts/blob/master/README.md

Provides a quick example of using the `buildUrl` function to construct a URL with a base URL, a specific path, and query parameters.

```typescript
import { buildUrl } from 'build-url-ts';

const url = buildUrl('https://api.example.com', {
  path: 'users/123',
  queryParams: {
    tab: 'profile',
    limit: 10
  }
});
// Result: https://api.example.com/users/123?tab=profile&limit=10
```

--------------------------------

### Install build-url-ts with npm, yarn, or pnpm

Source: https://github.com/meabed/build-url-ts/blob/master/README.md

Demonstrates how to install the build-url-ts library using different package managers like npm, yarn, and pnpm.

```bash
# npm
npm install build-url-ts

# yarn
yarn add build-url-ts

# pnpm
pnpm add build-url-ts
```

--------------------------------

### Build URL with path, query parameters, and hash

Source: https://github.com/meabed/build-url-ts/blob/master/README.md

An example combining path, query parameters, and a hash fragment to construct a complete URL.

```typescript
import { buildUrl } from 'build-url-ts';

// All combined
buildUrl('https://api.example.com', {
  path: 'v1/users',
  queryParams: {
    role: 'admin',
    active: true
  },
  hash: 'summary'
});
// → https://api.example.com/v1/users?role=admin&active=true#summary
```

--------------------------------

### Build URL with path

Source: https://github.com/meabed/build-url-ts/blob/master/README.md

Example of creating a URL with a base URL and a specified path.

```typescript
import { buildUrl } from 'build-url-ts';

// Simple URL with path
buildUrl('https://example.com', {
  path: 'about'
});
// → https://example.com/about
```

--------------------------------

### Convert URL components to lowercase

Source: https://github.com/meabed/build-url-ts/blob/master/README.md

Example of using the `lowerCase` option to convert path, query parameter keys/values, and hash to lowercase.

```typescript
import { buildUrl } from 'build-url-ts';

// Convert to lowercase
buildUrl('https://example.com', {
  path: 'About',
  hash: 'Contact',
  queryParams: {
    Filter: 'NEW'
  },
  lowerCase: true
});
// → https://example.com/about?filter=new#contact
```

--------------------------------

### Build Partial URLs with Query String, Path, or Hash

Source: https://github.com/meabed/build-url-ts/blob/master/README.md

Demonstrates how to construct URLs by specifying only the query string, path, or hash. It also shows how to use options as the first parameter for building a complete URL with path and query parameters.

```typescript
// Query string only
buildUrl(null, {
  queryParams: {
    page: 1,
    limit: 20
  }
});
// → ?page=1&limit=20

// Path only
buildUrl(null, {
  path: 'users/profile'
});
// → /users/profile

// Hash only
buildUrl(null, {
  hash: 'top'
});
// → #top

// Using options as first parameter
buildUrl({
  path: 'api/v2',
  queryParams: {
    format: 'json'
  }
});
// → /api/v2?format=json
```

--------------------------------

### Common npm Commands for build-url-ts

Source: https://github.com/meabed/build-url-ts/blob/master/README.md

Provides essential npm commands for managing the build-url-ts library, including running tests, executing tests in watch mode, building the library, and performing linting and type checking.

```bash
npm test
```

```bash
npm run test-watch
```

```bash
npm run build
```

```bash
npm run lint
```

```bash
npm run typecheck
```

--------------------------------

### Build URL with query parameters

Source: https://github.com/meabed/build-url-ts/blob/master/README.md

Demonstrates how to append query parameters to a URL using the `buildUrl` function.

```typescript
import { buildUrl } from 'build-url-ts';

// With query parameters
buildUrl('https://example.com', {
  path: 'search',
  queryParams: {
    q: 'typescript',
    category: 'tutorials'
  }
});
// → https://example.com/search?q=typescript&category=tutorials
```

--------------------------------

### Handle arrays with indexed notation (ascending)

Source: https://github.com/meabed/build-url-ts/blob/master/README.md

Demonstrates creating query parameters with indexed array notation, ordered ascendingly.

```typescript
import { buildUrl } from 'build-url-ts';

// Arrays with indexed notation (ascending)
buildUrl('https://api.example.com', {
  queryParams: {
    id: [1, 2, 3]
  },
  disableCSV: 'order_asc'
});
// → https://api.example.com?id[0]=1&id[1]=2&id[2]=3
```

--------------------------------

### Use Individual Functions for Granular Control

Source: https://github.com/meabed/build-url-ts/blob/master/README.md

Shows how to use the individually exported functions from build-url-ts for more specific URL manipulation, such as building query strings, appending paths, and creating hash fragments.

```typescript
import { 
  buildQueryString, 
  appendPath, 
  buildHash 
} from 'build-url-ts';

// Build query string only
const qs = buildQueryString({
  search: 'typescript',
  limit: 10
});
// → ?search=typescript&limit=10

// Append path to URL
const urlWithPath = appendPath('users/123', 'https://api.example.com');
// → https://api.example.com/users/123

// Build hash fragment
const hash = buildHash('section-2');
// → #section-2
```

--------------------------------

### Handle arrays with bracket notation

Source: https://github.com/meabed/build-url-ts/blob/master/README.md

Illustrates using bracket notation for array parameters in query strings.

```typescript
import { buildUrl } from 'build-url-ts';

// Arrays with bracket notation
buildUrl('https://api.example.com', {
  queryParams: {
    id: [1, 2, 3]
  },
  disableCSV: 'array'
});
// → https://api.example.com?id[]=1&id[]=2&id[]=3
```

--------------------------------

### Handle arrays with indexed notation (descending)

Source: https://github.com/meabed/build-url-ts/blob/master/README.md

Shows how to generate query parameters with indexed array notation, ordered descendingly.

```typescript
import { buildUrl } from 'build-url-ts';

// Arrays with indexed notation (descending)
buildUrl('https://api.example.com', {
  queryParams: {
    id: [1, 2, 3]
  },
  disableCSV: 'order_desc'
});
// → https://api.example.com?id[2]=1&id[1]=2&id[0]=3
```

--------------------------------

### Import build-url-ts in TypeScript

Source: https://github.com/meabed/build-url-ts/blob/master/README.md

Demonstrates how to import the buildUrl function from the 'build-url-ts' library in a TypeScript project, contrasting it with the CommonJS import from the original 'build-url' package.

```javascript
var buildUrl = require('build-url');
```

```typescript
import { buildUrl } from 'build-url-ts';
```

--------------------------------

### Build URL with hash fragment

Source: https://github.com/meabed/build-url-ts/blob/master/README.md

Shows how to add a hash fragment (or anchor) to the end of a URL.

```typescript
import { buildUrl } from 'build-url-ts';

// With hash
buildUrl('https://example.com', {
  path: 'docs',
  hash: 'installation'
});
// → https://example.com/docs#installation
```

--------------------------------

### Handle arrays as repeated parameters

Source: https://github.com/meabed/build-url-ts/blob/master/README.md

Shows how to configure `build-url-ts` to represent array values as repeated query parameters.

```typescript
import { buildUrl } from 'build-url-ts';

// Arrays as repeated parameters
buildUrl('https://api.example.com', {
  queryParams: {
    id: [1, 2, 3]
  },
  disableCSV: true
});
// → https://api.example.com?id=1&id=2&id=3
```

--------------------------------

### URL Encoding of Special Characters and Unicode

Source: https://github.com/meabed/build-url-ts/blob/master/README.md

Illustrates how build-url-ts automatically handles URL encoding for special characters, spaces, and Unicode characters within query parameters to ensure valid URL construction.

```typescript
buildUrl('https://example.com', {
  queryParams: {
    name: 'John Doe',
    email: 'john@example.com',
    message: 'Hello & goodbye!',
    unicode: '你好世界'
  }
});
// → https://example.com?name=John%20Doe&email=john%40example.com&message=Hello%20%26%20goodbye!&unicode=%E4%BD%A0%E5%A5%BD%E4%B8%96%E7%95%8C
```

--------------------------------

### Handle Edge Cases in URL Construction

Source: https://github.com/meabed/build-url-ts/blob/master/README.md

Covers various edge cases handled by build-url-ts, including empty or missing base URLs, trailing slashes, empty parameter values, merging existing query parameters, URLs with ports/authentication, special protocols, internationalized domain names, and empty arrays.

```typescript
// Empty or missing base URL
buildUrl('', { path: 'api' }); // → /api
buildUrl(null, { path: 'api' }); // → /api
buildUrl(undefined, { path: 'api' }); // → /api

// Trailing slashes
buildUrl('https://example.com/', { path: '/users' }); 
// → https://example.com/users (no double slash)

// Empty values
buildUrl('https://example.com', {
  path: '',      // ignored
  hash: '',      // ignored
  queryParams: {
    empty: '',   // included as empty
    zero: 0,     // included as "0"
    false: false // included as "false"
  }
});
// → https://example.com?empty=&zero=0&false=false

// URLs with existing query parameters (automatic merging)
buildUrl('https://example.com?existing=param', {
  queryParams: {
    new: 'value'
  }
});
// → https://example.com?existing=param&new=value

// URLs with ports and authentication
buildUrl('http://user:pass@localhost:3000', {
  path: 'api/secure'
});
// → http://user:pass@localhost:3000/api/secure

// Special protocols
buildUrl('file:///home/user/data', {
  queryParams: { version: 2 }
});
// → file:///home/user/data?version=2

// Internationalized domain names and emoji
buildUrl('https://例え.jp', {
  queryParams: {
    search: '🔍',
    text: '你好'
  }
});
// → https://例え.jp?search=%F0%9F%94%8D&text=%E4%BD%A0%E5%A5%BD

// Empty arrays are omitted
buildUrl('https://api.example.com', {
  queryParams: {
    ids: [],
    name: 'test'
  }
});
// → https://api.example.com?name=test

// Arrays with null/undefined values
buildUrl('https://api.example.com', {
  queryParams: {
    items: ['one', null, undefined, 'four']
  },
  disableCSV: true
});
// → https://api.example.com?items=one&items=&items=four
// (undefined values are filtered out)
```

--------------------------------

### Define Custom TypeScript Types for URL Parameters

Source: https://github.com/meabed/build-url-ts/blob/master/README.md

Demonstrates how to leverage TypeScript by defining custom types that extend the library's built-in types for query parameters and URL options, enabling better type safety and code completion.

```typescript
import type { 
  IQueryParams, 
  IBuildUrlOptions,
  IDisableCsvType 
} from 'build-url-ts';

// Custom query params type
interface MyParams extends IQueryParams {
  userId: number;
  tags?: string[];
  active?: boolean;
}

const options: IBuildUrlOptions = {
  path: 'api/users',
  queryParams: {
    userId: 123,
    tags: ['admin', 'verified']
  } as MyParams
};
```

--------------------------------

### Handle arrays as comma-separated values in query parameters

Source: https://github.com/meabed/build-url-ts/blob/master/README.md

Demonstrates the default behavior of `build-url-ts` where array values in query parameters are joined by commas.

```typescript
import { buildUrl } from 'build-url-ts';

// Default: Arrays as comma-separated values
buildUrl('https://api.example.com', {
  queryParams: {
    ids: [1, 2, 3]
  }
});
// → https://api.example.com?ids=1,2,3
```

--------------------------------

### Handle Special Values in URL Parameters

Source: https://github.com/meabed/build-url-ts/blob/master/README.md

Illustrates how build-url-ts handles various special values when constructing URL query parameters, including null, undefined, numbers, booleans, Date objects, and nested objects.

```typescript
// Null values become empty strings
buildUrl('https://api.example.com', {
  queryParams: {
    name: 'John',
    age: null
  }
});
// → https://api.example.com?name=John&age=

// Undefined values are omitted
buildUrl('https://api.example.com', {
  queryParams: {
    name: 'John',
    age: undefined
  }
});
// → https://api.example.com?name=John

// Number values
buildUrl('https://api.example.com', {
  path: 404,
  queryParams: {
    code: 0,
    retry: 3
  }
});
// → https://api.example.com/404?code=0&retry=3

// Boolean values
buildUrl('https://api.example.com', {
  queryParams: {
    active: true,
    deleted: false
  }
});
// → https://api.example.com?active=true&deleted=false

// Date objects
const date = new Date('2024-01-01T00:00:00Z');
buildUrl('https://api.example.com', {
  queryParams: {
    created: date
  }
});
// → https://api.example.com?created=Mon%20Jan%2001%202024...

// Nested objects (automatically stringified)
buildUrl('https://api.example.com', {
  queryParams: {
    filter: { status: 'active', role: 'admin' }
  }
});
// → https://api.example.com?filter=%7B%22status%22%3A%22active%22%2C%22role%22%3A%22admin%22%7D
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.