@sectui/operations 0.0.0-stage → 0.1.0

package/src/completions.ts

@@ -0,0 +1,129 @@
+import { cliFlag } from "./cli-flags.ts";
+import type { Operation } from "./operation.ts";
+import { operations } from "./registry.ts";
+
+export const SHELLS = ["bash", "zsh", "fish"] as const;
+export type Shell = (typeof SHELLS)[number];
+
+const COMMANDS = [
+  ["list", "List available operations"],
+  ["help", "Show help"],
+  ["render", "Replace operation{...} blocks in text"],
+  ["completions", "Print a shell completion script"],
+] as const;
+
+const GLOBAL_FLAGS = [
+  ["--raw", "Write raw bytes even to a terminal"],
+  ["--help", "Show help"],
+] as const;
+
+const ops = operations as readonly Operation[];
+
+/** Wraps a string in single quotes for any POSIX-like shell. */
+const sq = (s: string) => `'${s.replaceAll("'", `'\\''`)}'`;
+
+interface Flag {
+  flag: string;
+  description: string;
+  values?: string[];
+}
+
+function flagsOf(op: Operation): Flag[] {
+  return Object.entries(op.args).map(([key, def]) => ({
+    flag: cliFlag(key, def),
+    description: def.name,
+    values: def.type === "select" ? def.options.map((o) => o.value) : def.type === "boolean" ? undefined : [],
+  }));
+}
+
+function bash(): string {
+  const ids = ops.map((op) => op.id).join(" ");
+  const cases = ops.map((op) => {
+    const flags = flagsOf(op);
+    const valueCases = flags
+      .filter((f) => f.values)
+      .map((f) => `        ${f.flag}) COMPREPLY=($(compgen -W ${sq(f.values!.join(" "))} -- "$cur")); return ;;`);
+    const all = [...flags.map((f) => f.flag), ...GLOBAL_FLAGS.map(([f]) => f)].join(" ");
+    return [
+      `    ${op.id})`,
+      ...(valueCases.length ? ['      case "$prev" in', ...valueCases, "      esac"] : []),
+      `      [[ $cur == -* ]] && COMPREPLY=($(compgen -W ${sq(all)} -- "$cur"))`,
+      "      ;;",
+    ].join("\n");
+  });
+  return `# bash completion for ops
+_ops() {
+  local cur="\${COMP_WORDS[COMP_CWORD]}" prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  if (( COMP_CWORD == 1 )); then
+    COMPREPLY=($(compgen -W ${sq(`${COMMANDS.map(([c]) => c).join(" ")} ${ids}`)} -- "$cur"))
+    return
+  fi
+  case "\${COMP_WORDS[1]}" in
+    help) (( COMP_CWORD == 2 )) && COMPREPLY=($(compgen -W ${sq(ids)} -- "$cur")) ;;
+    completions) (( COMP_CWORD == 2 )) && COMPREPLY=($(compgen -W ${sq(SHELLS.join(" "))} -- "$cur")) ;;
+    render) [[ $cur == -* ]] && COMPREPLY=($(compgen -W ${sq(GLOBAL_FLAGS.map(([f]) => f).join(" "))} -- "$cur")) ;;
+${cases.join("\n")}
+  esac
+}
+complete -F _ops ops
+`;
+}
+
+function zsh(): string {
+  // Escapes characters that are special in _describe entries and _arguments specs.
+  const esc = (s: string) => s.replace(/([:[\]\\])/g, "\\$1");
+  const describe = (items: (readonly [string, string])[]) => items.map(([n, d]) => sq(`${esc(n)}:${esc(d)}`)).join(" ");
+  const globals = GLOBAL_FLAGS.map(([f, d]) => sq(`${f}[${esc(d)}]`)).join(" ");
+  const cases = ops.map((op) => {
+    const specs = flagsOf(op).map((f) => {
+      const action = f.values === undefined ? "" : f.values.length ? `:value:(${f.values.join(" ")})` : ":value:";
+      return sq(`${f.flag}[${esc(f.description)}]${action}`);
+    });
+    return `    ${op.id}) _arguments ${[...specs, globals, sq("*:input:")].join(" ")} ;;`;
+  });
+  return `#compdef ops
+_ops() {
+  if (( CURRENT == 2 )); then
+    local -a commands=(${describe([...COMMANDS, ...ops.map((op) => [op.id, op.name] as const)])})
+    _describe command commands
+    return
+  fi
+  local cmd=$words[2]
+  shift words
+  (( CURRENT-- ))
+  case $cmd in
+    help) (( CURRENT == 2 )) && { local -a ids=(${describe(ops.map((op) => [op.id, op.name] as const))}); _describe operation ids } ;;
+    completions) (( CURRENT == 2 )) && _values shell ${SHELLS.join(" ")} ;;
+    render) _arguments ${globals} ${sq("*:text:")} ;;
+${cases.join("\n")}
+  esac
+}
+if [[ $funcstack[1] == _ops ]]; then _ops "$@"; else compdef _ops ops; fi
+`;
+}
+
+function fish(): string {
+  const lines = ["# fish completion for ops", "complete -c ops -f"];
+  for (const [command, description] of COMMANDS) {
+    lines.push(`complete -c ops -n __fish_use_subcommand -a ${command} -d ${sq(description)}`);
+  }
+  for (const op of ops) lines.push(`complete -c ops -n __fish_use_subcommand -a ${op.id} -d ${sq(op.name)}`);
+  const ids = sq(ops.map((op) => op.id).join(" "));
+  lines.push(`complete -c ops -n '__fish_seen_subcommand_from help' -a ${ids}`);
+  lines.push(`complete -c ops -n '__fish_seen_subcommand_from completions' -a ${sq(SHELLS.join(" "))}`);
+  const withGlobals = ["render", ...ops.map((op) => op.id)].join(" ");
+  for (const [flag, description] of GLOBAL_FLAGS) {
+    lines.push(`complete -c ops -n ${sq(`__fish_seen_subcommand_from ${withGlobals}`)} -l ${flag.slice(2)} -d ${sq(description)}`);
+  }
+  for (const op of ops) {
+    for (const f of flagsOf(op)) {
+      const values = f.values === undefined ? "" : f.values.length ? ` -x -a ${sq(f.values.join(" "))}` : " -x";
+      lines.push(`complete -c ops -n ${sq(`__fish_seen_subcommand_from ${op.id}`)} -l ${f.flag.slice(2)}${values} -d ${sq(f.description)}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export function completions(shell: Shell): string {
+  return { bash, zsh, fish }[shell]();
+}

package/src/display.ts

@@ -0,0 +1,29 @@
+// C0 controls except tab/LF/CR, DEL, C1 controls (e.g. U+009B is a CSI on some terminals),
+// and bidi overrides that can make text display differently from its content.
+const UNSAFE_CHARS = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f‪-‮⁦-⁩]/;
+
+/** True if the bytes are valid UTF-8 text without characters that can control a terminal. */
+export function isPrintable(bytes: Uint8Array): boolean {
+  let text: string;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return false;
+  }
+  return !UNSAFE_CHARS.test(text);
+}
+
+/** Canonical hex+ASCII dump, like `hexdump -C`. */
+export function hexdump(bytes: Uint8Array): string {
+  const lines: string[] = [];
+  for (let offset = 0; offset < bytes.length; offset += 16) {
+    const row = bytes.subarray(offset, offset + 16);
+    const hex = [...row].map((b) => b.toString(16).padStart(2, "0"));
+    const left = hex.slice(0, 8).join(" ");
+    const right = hex.slice(8).join(" ");
+    const ascii = [...row].map((b) => (b >= 0x20 && b < 0x7f ? String.fromCharCode(b) : ".")).join("");
+    lines.push(`${offset.toString(16).padStart(8, "0")}  ${left.padEnd(23)}  ${right.padEnd(23)}  |${ascii}|`);
+  }
+  lines.push(bytes.length.toString(16).padStart(8, "0"));
+  return lines.join("\n");
+}

package/src/errors.ts

@@ -0,0 +1,6 @@
+/** Error raised when an operation cannot process its input or arguments. */
+export class OperationError extends Error {
+  override name = "OperationError";
+  /** Id of the failing operation, set by `run`. */
+  operation?: string;
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./display.ts";
+export * from "./errors.ts";
+export * from "./operation.ts";
+export * from "./registry.ts";

package/src/operation.ts

@@ -0,0 +1,62 @@
+export type Category = "Encoding" | "Encryption" | "Hashing" | "Compression" | "Data format" | "Text" | "Extractors" | "Utils";
+
+interface BaseArg<T> {
+  name: string;
+  description?: string;
+  default: T;
+}
+
+export type ArgDef =
+  | ({ type: "boolean" } & BaseArg<boolean>)
+  | ({ type: "string" } & BaseArg<string>)
+  | ({ type: "number"; min?: number; max?: number } & BaseArg<number>)
+  | ({ type: "select"; options: readonly { value: string; label: string }[] } & BaseArg<string>);
+
+export type ArgDefs = Record<string, ArgDef>;
+
+/** A select arg resolves to the union of its option values. */
+export type ArgValue<D extends ArgDef> = D extends { type: "select"; options: readonly { value: infer V }[] }
+  ? V
+  : D extends { type: "boolean" }
+    ? boolean
+    : D extends { type: "number" }
+      ? number
+      : string;
+
+export type ArgValues<A extends ArgDefs> = {
+  [K in keyof A]: ArgValue<A[K]>;
+};
+
+export interface Example<A extends ArgDefs = ArgDefs> {
+  input: string;
+  args?: Partial<ArgValues<A>>;
+  /** Expected output, decoded as UTF-8. */
+  output: string;
+}
+
+export interface Operation<Id extends string = string, A extends ArgDefs = ArgDefs, Inverse extends string = string> {
+  /** Stable kebab-case id, used in templates and recipes. */
+  id: Id;
+  name: string;
+  description: string;
+  category: Category;
+  /** `binary` when the output may contain arbitrary bytes, so callers know not to print it as text. */
+  output: "text" | "binary";
+  /** Extra search terms. */
+  aliases?: readonly string[];
+  /** Id of the operation that undoes this one. */
+  inverse?: Inverse;
+  infoUrl?: string;
+  /** Keyed by arg id, in display order. */
+  args: A;
+  /** Shown in the docs and the CLI help, and checked by the test suite. */
+  examples: readonly [Example<A>, ...Example<A>[]];
+  run(input: Uint8Array, args: ArgValues<A>): Uint8Array;
+}
+
+/** Identity function that preserves the literal types of the id, args and inverse. */
+export function defineOperation<const Id extends string, const A extends ArgDefs, const Inverse extends string = never>(
+  op: Operation<Id, A, Inverse>,
+): Operation<Id, A, Inverse> {
+  return op;
+}

package/src/operations/base/alphabets.ts

@@ -0,0 +1,33 @@
+export const BASE32_ALPHABETS = [
+  { value: "base32", label: "Standard (RFC 4648): A-Z2-7=" },
+  { value: "base32hex", label: "Extended hex (RFC 4648 §7): 0-9A-V=" },
+] as const;
+
+export type Base32Alphabet = (typeof BASE32_ALPHABETS)[number]["value"];
+
+export const BASE32_CHARS: Record<Base32Alphabet, string> = {
+  base32: "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567",
+  base32hex: "0123456789ABCDEFGHIJKLMNOPQRSTUV",
+};
+
+export const BASE58_ALPHABETS = [
+  { value: "bitcoin", label: "Bitcoin: 1-9A-HJ-NP-Za-km-z" },
+  { value: "flickr", label: "Flickr: 1-9a-km-zA-HJ-NP-Z" },
+  { value: "ripple", label: "Ripple: rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz" },
+] as const;
+
+export const BASE58_CHARS: Record<(typeof BASE58_ALPHABETS)[number]["value"], string> = {
+  bitcoin: "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz",
+  flickr: "123456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ",
+  ripple: "rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz",
+};
+
+export const BASE62_ALPHABETS = [
+  { value: "0-9A-Za-z", label: "Digits, uppercase, lowercase (GMP)" },
+  { value: "0-9a-zA-Z", label: "Digits, lowercase, uppercase" },
+] as const;
+
+export const BASE62_CHARS: Record<(typeof BASE62_ALPHABETS)[number]["value"], string> = {
+  "0-9A-Za-z": "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
+  "0-9a-zA-Z": "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ",
+};

package/src/operations/base/base32.ts

@@ -0,0 +1,84 @@
+import { OperationError } from "../../errors.ts";
+import { defineOperation } from "../../operation.ts";
+import { BASE32_ALPHABETS, BASE32_CHARS } from "./alphabets.ts";
+
+export const toBase32 = defineOperation({
+  id: "to-base32",
+  name: "To Base32",
+  description: 'Encodes raw bytes as Base32 text. e.g. "hello" becomes "NBSWY3DP".',
+  category: "Encoding",
+  output: "text",
+  aliases: ["b32", "base32 encode"],
+  inverse: "from-base32",
+  infoUrl: "https://wikipedia.org/wiki/Base32",
+  args: {
+    alphabet: { type: "select", name: "Alphabet", options: BASE32_ALPHABETS, default: "base32" },
+    padding: { type: "boolean", name: "Padding (=)", default: true },
+  },
+  examples: [
+    { input: "hello", output: "NBSWY3DP" },
+    { input: "hi", output: "NBUQ====" },
+    { input: "hi", args: { alphabet: "base32hex", padding: false }, output: "D1KG" },
+  ],
+  run(input, { alphabet, padding }) {
+    const chars = BASE32_CHARS[alphabet];
+    let out = "";
+    let buffer = 0;
+    let bits = 0;
+    for (const byte of input) {
+      buffer = ((buffer << 8) | byte) & 0xfff;
+      bits += 8;
+      while (bits >= 5) {
+        bits -= 5;
+        out += chars[(buffer >> bits) & 31];
+      }
+    }
+    if (bits > 0) out += chars[(buffer << (5 - bits)) & 31];
+    if (padding) out = out.padEnd(Math.ceil(out.length / 8) * 8, "=");
+    return new TextEncoder().encode(out);
+  },
+});
+
+// Number of characters in a final group that can encode whole bytes (2 -> 1 byte, 4 -> 2, 5 -> 3, 7 -> 4).
+const VALID_TAIL = new Set([0, 2, 4, 5, 7]);
+
+export const fromBase32 = defineOperation({
+  id: "from-base32",
+  name: "From Base32",
+  description: 'Decodes Base32 text into raw bytes, ignoring case, whitespace and padding. e.g. "NBSWY3DP" becomes "hello".',
+  category: "Encoding",
+  output: "binary",
+  aliases: ["b32", "base32 decode"],
+  inverse: "to-base32",
+  infoUrl: "https://wikipedia.org/wiki/Base32",
+  args: {
+    alphabet: { type: "select", name: "Alphabet", options: BASE32_ALPHABETS, default: "base32" },
+  },
+  examples: [
+    { input: "NBSWY3DP", output: "hello" },
+    { input: "nbuq====", output: "hi" },
+    { input: "D1KG", args: { alphabet: "base32hex" }, output: "hi" },
+  ],
+  run(input, { alphabet }) {
+    const chars = BASE32_CHARS[alphabet];
+    const text = new TextDecoder().decode(input).replace(/\s+/g, "").replace(/=+$/, "").toUpperCase();
+    if (!VALID_TAIL.has(text.length % 8)) {
+      throw new OperationError("Invalid Base32: truncated input (the last group has an impossible length)");
+    }
+    const out = new Uint8Array(Math.floor((text.length * 5) / 8));
+    let n = 0;
+    let buffer = 0;
+    let bits = 0;
+    for (let i = 0; i < text.length; i++) {
+      const value = chars.indexOf(text[i]!);
+      if (value < 0) throw new OperationError(`Invalid Base32: unexpected character "${text[i]}"`);
+      buffer = ((buffer << 5) | value) & 0xfff;
+      bits += 5;
+      if (bits >= 8) {
+        bits -= 8;
+        out[n++] = (buffer >> bits) & 0xff;
+      }
+    }
+    return out;
+  },
+});

package/src/operations/base/base58.ts

@@ -0,0 +1,45 @@
+import { defineOperation } from "../../operation.ts";
+import { BASE58_ALPHABETS, BASE58_CHARS } from "./alphabets.ts";
+import { decodeBaseX, encodeBaseX } from "./big-number.ts";
+
+export const toBase58 = defineOperation({
+  id: "to-base58",
+  name: "To Base58",
+  description:
+    'Encodes raw bytes as Base58 text, as used by Bitcoin addresses. Leading zero bytes become "1". e.g. "hello" becomes "Cn8eVZg".',
+  category: "Encoding",
+  output: "text",
+  aliases: ["b58", "base58 encode", "bitcoin"],
+  inverse: "from-base58",
+  infoUrl: "https://wikipedia.org/wiki/Binary-to-text_encoding#Base58",
+  args: {
+    alphabet: { type: "select", name: "Alphabet", options: BASE58_ALPHABETS, default: "bitcoin" },
+  },
+  examples: [
+    { input: "hello", output: "Cn8eVZg" },
+    { input: "Hello World!", output: "2NEpo7TZRRrLZSi2U" },
+  ],
+  run: (input, { alphabet }) => new TextEncoder().encode(encodeBaseX(input, BASE58_CHARS[alphabet])),
+});
+
+export const fromBase58 = defineOperation({
+  id: "from-base58",
+  name: "From Base58",
+  description: 'Decodes Base58 text into raw bytes, ignoring whitespace. e.g. "Cn8eVZg" becomes "hello".',
+  category: "Encoding",
+  output: "binary",
+  aliases: ["b58", "base58 decode", "bitcoin"],
+  inverse: "to-base58",
+  infoUrl: "https://wikipedia.org/wiki/Binary-to-text_encoding#Base58",
+  args: {
+    alphabet: { type: "select", name: "Alphabet", options: BASE58_ALPHABETS, default: "bitcoin" },
+  },
+  examples: [
+    { input: "Cn8eVZg", output: "hello" },
+    { input: "2NEpo7TZRRrLZSi2U", output: "Hello World!" },
+  ],
+  run(input, { alphabet }) {
+    const text = new TextDecoder().decode(input).replace(/\s+/g, "");
+    return decodeBaseX(text, BASE58_CHARS[alphabet], "Base58");
+  },
+});

package/src/operations/base/base62.ts

@@ -0,0 +1,44 @@
+import { defineOperation } from "../../operation.ts";
+import { BASE62_ALPHABETS, BASE62_CHARS } from "./alphabets.ts";
+import { decodeBaseX, encodeBaseX } from "./big-number.ts";
+
+export const toBase62 = defineOperation({
+  id: "to-base62",
+  name: "To Base62",
+  description: 'Encodes raw bytes as Base62 text (letters and digits only). Leading zero bytes become "0". e.g. "hello" becomes "7tQLFHz".',
+  category: "Encoding",
+  output: "text",
+  aliases: ["b62", "base62 encode"],
+  inverse: "from-base62",
+  infoUrl: "https://wikipedia.org/wiki/Base62",
+  args: {
+    alphabet: { type: "select", name: "Alphabet", options: BASE62_ALPHABETS, default: "0-9A-Za-z" },
+  },
+  examples: [
+    { input: "hello", output: "7tQLFHz" },
+    { input: "hello", args: { alphabet: "0-9a-zA-Z" }, output: "7TqlfhZ" },
+  ],
+  run: (input, { alphabet }) => new TextEncoder().encode(encodeBaseX(input, BASE62_CHARS[alphabet])),
+});
+
+export const fromBase62 = defineOperation({
+  id: "from-base62",
+  name: "From Base62",
+  description: 'Decodes Base62 text into raw bytes, ignoring whitespace. e.g. "7tQLFHz" becomes "hello".',
+  category: "Encoding",
+  output: "binary",
+  aliases: ["b62", "base62 decode"],
+  inverse: "to-base62",
+  infoUrl: "https://wikipedia.org/wiki/Base62",
+  args: {
+    alphabet: { type: "select", name: "Alphabet", options: BASE62_ALPHABETS, default: "0-9A-Za-z" },
+  },
+  examples: [
+    { input: "7tQLFHz", output: "hello" },
+    { input: "7TqlfhZ", args: { alphabet: "0-9a-zA-Z" }, output: "hello" },
+  ],
+  run(input, { alphabet }) {
+    const text = new TextDecoder().decode(input).replace(/\s+/g, "");
+    return decodeBaseX(text, BASE62_CHARS[alphabet], "Base62");
+  },
+});

package/src/operations/base/base64.ts

@@ -0,0 +1,76 @@
+import { OperationError } from "../../errors.ts";
+import { defineOperation } from "../../operation.ts";
+
+type Base64Alphabet = "base64" | "base64url";
+
+const NON_ALPHABET: Record<Base64Alphabet, RegExp> = {
+  base64: /[^A-Za-z0-9+/]/g,
+  base64url: /[^A-Za-z0-9\-_]/g,
+};
+
+function invalidInput(text: string, alphabet: Base64Alphabet, strict: boolean): OperationError {
+  if (strict) {
+    const unpadded = text.replace(/=+$/, "");
+    const bad = new RegExp(NON_ALPHABET[alphabet].source).exec(unpadded);
+    if (bad) return new OperationError(`Invalid Base64: unexpected character "${bad[0]}" at offset ${bad.index}`);
+    return new OperationError("Invalid Base64: missing or incorrect padding");
+  }
+  return new OperationError("Invalid Base64: truncated input (the last group has a single character)");
+}
+
+export function encodeBase64(input: Uint8Array, alphabet: Base64Alphabet, padding: boolean): Uint8Array {
+  return new TextEncoder().encode(input.toBase64({ alphabet, omitPadding: !padding }));
+}
+
+export function decodeBase64(input: Uint8Array, alphabet: Base64Alphabet, strict: boolean): Uint8Array {
+  let text = new TextDecoder().decode(input);
+  if (!strict) text = text.replace(NON_ALPHABET[alphabet], "");
+  try {
+    return Uint8Array.fromBase64(text, { alphabet, lastChunkHandling: strict ? "strict" : "loose" });
+  } catch {
+    throw invalidInput(text, alphabet, strict);
+  }
+}
+
+export const toBase64 = defineOperation({
+  id: "to-base64",
+  name: "To Base64",
+  description: 'Encodes raw bytes as Base64 text. e.g. "hello" becomes "aGVsbG8=".',
+  category: "Encoding",
+  output: "text",
+  aliases: ["b64", "base64 encode"],
+  inverse: "from-base64",
+  infoUrl: "https://wikipedia.org/wiki/Base64",
+  args: {
+    padding: { type: "boolean", name: "Padding (=)", default: true },
+  },
+  examples: [
+    { input: "hello", output: "aGVsbG8=" },
+    { input: "hello", args: { padding: false }, output: "aGVsbG8" },
+  ],
+  run: (input, { padding }) => encodeBase64(input, "base64", padding),
+});
+
+export const fromBase64 = defineOperation({
+  id: "from-base64",
+  name: "From Base64",
+  description: 'Decodes Base64 text into raw bytes. e.g. "aGVsbG8=" becomes "hello".',
+  category: "Encoding",
+  output: "binary",
+  aliases: ["b64", "base64 decode"],
+  inverse: "to-base64",
+  infoUrl: "https://wikipedia.org/wiki/Base64",
+  args: {
+    strict: {
+      type: "boolean",
+      name: "Strict mode",
+      description: "Fail on non-alphabet characters and invalid padding instead of ignoring them.",
+      default: false,
+    },
+  },
+  examples: [
+    { input: "aGVsbG8=", output: "hello" },
+    { input: "aGVs\nbG8", output: "hello" },
+  ],
+  run: (input, { strict }) => decodeBase64(input, "base64", strict),
+});

package/src/operations/base/base64url.ts

@@ -0,0 +1,45 @@
+import { defineOperation } from "../../operation.ts";
+import { decodeBase64, encodeBase64 } from "./base64.ts";
+
+export const toBase64url = defineOperation({
+  id: "to-base64url",
+  name: "To Base64url",
+  description: 'Encodes raw bytes as URL-safe Base64 (- and _ instead of + and /), without padding by default. e.g. "ÿÿ" becomes "w7_Dvw".',
+  category: "Encoding",
+  output: "text",
+  aliases: ["b64url", "base64url encode"],
+  inverse: "from-base64url",
+  infoUrl: "https://datatracker.ietf.org/doc/html/rfc4648#section-5",
+  args: {
+    padding: { type: "boolean", name: "Padding (=)", default: false },
+  },
+  examples: [
+    { input: "ÿÿ", output: "w7_Dvw" },
+    { input: "ÿÿ", args: { padding: true }, output: "w7_Dvw==" },
+  ],
+  run: (input, { padding }) => encodeBase64(input, "base64url", padding),
+});
+
+export const fromBase64url = defineOperation({
+  id: "from-base64url",
+  name: "From Base64url",
+  description: 'Decodes URL-safe Base64 (- and _ instead of + and /) into raw bytes. e.g. "w7_Dvw" becomes "ÿÿ".',
+  category: "Encoding",
+  output: "binary",
+  aliases: ["b64url", "base64url decode", "jwt"],
+  inverse: "to-base64url",
+  infoUrl: "https://datatracker.ietf.org/doc/html/rfc4648#section-5",
+  args: {
+    strict: {
+      type: "boolean",
+      name: "Strict mode",
+      description: "Fail on non-alphabet characters and invalid padding instead of ignoring them.",
+      default: false,
+    },
+  },
+  examples: [
+    { input: "w7_Dvw", output: "ÿÿ" },
+    { input: "w7_Dvw==", output: "ÿÿ" },
+  ],
+  run: (input, { strict }) => decodeBase64(input, "base64url", strict),
+});

package/src/operations/base/big-number.ts

@@ -0,0 +1,54 @@
+import { OperationError } from "../../errors.ts";
+
+/**
+ * Encodes bytes as a big number in the given base. Each leading zero byte becomes the alphabet's
+ * first character, so they survive a round trip (as in Bitcoin's Base58).
+ */
+export function encodeBaseX(input: Uint8Array, alphabet: string): string {
+  const base = alphabet.length;
+  let zeros = 0;
+  while (zeros < input.length && input[zeros] === 0) zeros++;
+  // Little-endian digits of the number.
+  const digits: number[] = [];
+  for (let i = zeros; i < input.length; i++) {
+    let carry = input[i]!;
+    for (let j = 0; j < digits.length; j++) {
+      carry += digits[j]! << 8;
+      digits[j] = carry % base;
+      carry = Math.floor(carry / base);
+    }
+    while (carry > 0) {
+      digits.push(carry % base);
+      carry = Math.floor(carry / base);
+    }
+  }
+  return (
+    alphabet[0]!.repeat(zeros) +
+    digits
+      .reverse()
+      .map((d) => alphabet[d])
+      .join("")
+  );
+}
+
+export function decodeBaseX(text: string, alphabet: string, name: string): Uint8Array {
+  const base = alphabet.length;
+  let zeros = 0;
+  while (zeros < text.length && text[zeros] === alphabet[0]) zeros++;
+  // Little-endian bytes of the number.
+  const bytes: number[] = [];
+  for (let i = zeros; i < text.length; i++) {
+    let carry = alphabet.indexOf(text[i]!);
+    if (carry < 0) throw new OperationError(`Invalid ${name}: unexpected character "${text[i]}"`);
+    for (let j = 0; j < bytes.length; j++) {
+      carry += bytes[j]! * base;
+      bytes[j] = carry & 0xff;
+      carry >>= 8;
+    }
+    while (carry > 0) {
+      bytes.push(carry & 0xff);
+      carry >>= 8;
+    }
+  }
+  return new Uint8Array([...new Array<number>(zeros).fill(0), ...bytes.reverse()]);
+}

package/src/operations/color/hex-to-rgb.ts

@@ -0,0 +1,42 @@
+import { OperationError } from "../../errors.ts";
+import { defineOperation } from "../../operation.ts";
+import { mapLines, mapText } from "../text/lines.ts";
+
+const FORMATS = [
+  { value: "css", label: "CSS: rgb(255, 136, 0) or rgba(255, 136, 0, 0.5)" },
+  { value: "values", label: "Values: 255, 136, 0" },
+] as const;
+
+function toRgb(color: string, format: (typeof FORMATS)[number]["value"]): string {
+  const hex = color.trim().replace(/^#/, "");
+  if (!/^(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(hex)) {
+    throw new OperationError(`Invalid hex color "${color.trim()}": expected #rgb, #rgba, #rrggbb or #rrggbbaa`);
+  }
+  const full = hex.length <= 4 ? [...hex].map((c) => c + c).join("") : hex;
+  const [r, g, b, a] = full.match(/../g)!.map((pair) => parseInt(pair, 16));
+  const values = [r, g, b];
+  // Alpha as a fraction, rounded to what 8 bits can tell apart.
+  if (a !== undefined) values.push(Math.round((a / 255) * 1000) / 1000);
+  if (format === "values") return values.join(", ");
+  return `${a === undefined ? "rgb" : "rgba"}(${values.join(", ")})`;
+}
+
+export const hexToRgb = defineOperation({
+  id: "hex-to-rgb",
+  name: "Hex to RGB",
+  description: 'Converts hex colors (one per line) to RGB. e.g. "#ff8800" becomes "rgb(255, 136, 0)".',
+  category: "Data format",
+  output: "binary",
+  aliases: ["color", "colour", "css color"],
+  infoUrl: "https://developer.mozilla.org/docs/Web/CSS/hex-color",
+  args: {
+    format: { type: "select", name: "Format", options: FORMATS, default: "css" },
+  },
+  examples: [
+    { input: "#ff8800", output: "rgb(255, 136, 0)" },
+    { input: "#f80\n#FF880080", output: "rgb(255, 136, 0)\nrgba(255, 136, 0, 0.502)" },
+    { input: "ff8800", args: { format: "values" }, output: "255, 136, 0" },
+  ],
+  run: (input, { format }) =>
+    mapText(input, (text) => mapLines(text, (lines) => lines.map((line) => (line.trim() ? toRgb(line, format) : line)))),
+});