Bangs-DuckGo

bangs-duckgo is a library designed to work with DuckDuckGo bangs. It provides utilities to handle, parse, and work with these bangs in JavaScript or TypeScript environments.

Table of Contents

• Installation
• Usage
• API Reference
  • Types
    • RawBang
    • Bang
  • bangs
  • bangFrom
  • bangsFrom
  • parseBang
  • bangURL
  • rankedBangs
• Scripts
• Contributing
• License

Installation

You can install this library using npm, yarn, or bun.

# npm
npm install bangs-duckgo

# yarn
yarn add bangs-duckgo

# bun
bun add bangs-duckgo

Usage

Below is a basic example of how you can use this library:

import bangs from 'bangs-duckgo/bangs.json';

import { parseBang, bangURL, rankedBangs } from 'bangs-duckgo';

// Get all bangs
console.log(bangs);

const bang = bangs[0];
console.log(bang);

// Parse a string to get bang and query
const parsed = parseBang('!g search query');
console.log(parsed);

// Get the URL associated with a bang
const url = bangURL(bang, 'search query');
console.log(url);

// Get ranked bangs
const ranked = rankedBangs(bangs);
console.log(ranked);

API Reference

Types

RawBang

RawBang is a type that represents a raw bang object, typically as fetched from the bangs.json file.

import type { Raw } from 'bangs-duckgo';

Bang

Bang is a type that represents a formatted bang object.

import type { Bang } from 'bangs-duckgo';

import bangs

// use this import if you prefer raw bangs
import rawBangs from 'bangs-duckgo/raw-bangs.json';

// otherwise
import bangs from 'bangs-duckgo/bangs.json';

bangFrom(raw: RawBang): Bang

Converts a RawBang to a Bang.

export function bangFrom(raw: RawBang): Bang;

const formattedBang = bangFrom(rawBang);

bangsFrom(raws: RawBang[]): Generator

Generates Bang objects from an array of RawBang objects.

export function* bangsFrom(raws: RawBang[]): Generator<Bang>;

for (const bang of bangsFrom(rawBangs)) {
  console.log(bang);
}

parseBang(s: string): { bang: string; query: string } | undefined

Parses a string to extract a bang and its associated query.

export function parseBang(
  s: string,
): { bang: string; query: string } | undefined;

const parsed = parseBang('!g search query');
if (parsed) {
  console.log(parsed.bang); // 'g'
  console.log(parsed.query); // 'search query'
}

bangURL(item: RawBang | Bang, query: string): string

Generates the URL for a specific bang with the given query.

export function bangURL(item: RawBang | Bang, query: string): string;

const url = bangURL(formattedBang, 'search query');
console.log(url);

rankedBangs(bangs: Bang[]): Bang[]

rankedBangs(bangs: RawBang[]): RawBang[]

Sorts bangs based on their ratings in descending order.

export function rankedBangs(bangs: Bang[]): Bang[];
export function rankedBangs(bangs: RawBang[]): RawBang[];
export function rankedBangs(
  bangs: Array<Bang | RawBang>,
): Array<Bang | RawBang>;

const ranked = rankedBangs(bangs);
console.log(ranked);

Scripts

• build: Build the project using tsup.
• check-exports: Check the exports of the project using attw.
• check-format: Check the code formatting using prettier.
• fetch: Fetch and update the bangs.json file.
• format: Format the code using prettier.
• types: Generate TypeScript types from bangs.json.

Contributing

Contributions are welcome! Please visit our issues page to report bugs or request features.

License

This project is licensed under the MIT License. See the LICENSE file for details.