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, bangFrom, parseBang, bangURL, rankedBangs } from 'bangs-duckgo';

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

// Convert raw bang to a formatted bang
const formattedBang = bangFrom(bangs[0]);
console.log(formattedBang);

// 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(formattedBang, '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 './gen';

export type RawBang = Omit<Raw, 'c'> & { c?: Raw['c'] | (string & {}) };

Bang

Bang is a type that represents a formatted bang object.

export type Bang = {
  readonly url: RawBang['u'];
  readonly bang: RawBang['t'];
  readonly site: RawBang['s'];
  readonly domain: RawBang['d'];
  readonly rating: RawBang['r'];
  readonly category?: RawBang['c'];
  readonly subcategory?: RawBang['sc'];
};

bangs

An array of RawBang objects fetched from the bangs.json file.

export const bangs: RawBang[] = bangsJson;

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.