or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

caching-errors.mdindex.mdprotocols.md
tile.json

tessl/npm-get-uri

Returns a stream.Readable from a URI string supporting multiple protocols

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/get-uri@6.0.x

To install, run

npx @tessl/cli install tessl/npm-get-uri@6.0.0

index.mddocs/

get-uri

get-uri is a high-level URI-to-stream interface that accepts URI strings and returns Node.js Readable stream instances. It supports multiple protocols including data URIs, file URIs, FTP, HTTP, and HTTPS with built-in caching capabilities for performance optimization.

Package Information

  • Package Name: get-uri
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install get-uri

Core Imports

import { getUri } from "get-uri";

For CommonJS:

const { getUri } = require("get-uri");

Basic Usage

import { getUri } from "get-uri";

// Get a readable stream from a URI
const stream = await getUri('https://httpbin.org/json');
stream.pipe(process.stdout);

// Use with different protocols
const fileStream = await getUri('file:///path/to/file.txt');
const dataStream = await getUri('data:text/plain;base64,SGVsbG8gV29ybGQ=');
const ftpStream = await getUri('ftp://ftp.example.com/path/to/file.txt');

Architecture

get-uri is built around several key components:

  • Main Interface: The getUri() function provides a unified interface for all URI protocols
  • Protocol Registry: A modular system where each protocol has its own handler implementation
  • Caching System: Built-in cache validation to avoid redundant requests and downloads
  • Error Handling: Standardized error codes for missing resources (ENOTFOUND) and unchanged resources (ENOTMODIFIED)
  • Type Safety: Full TypeScript support with protocol-specific option types

Capabilities

Core Interface

Main function for converting URIs to readable streams with protocol-specific options and caching support.

/**
 * Returns a readable stream from a URI string
 * @param uri - URI string or URL object to retrieve
 * @param opts - Protocol-specific options including cache validation
 * @returns Promise that resolves to a readable stream
 * @throws TypeError for unsupported protocols or missing URI
 */
function getUri<Uri extends string>(
  uri: Uri | URL,
  opts?: ProtocolOpts<Uri>
): Promise<Readable>;

Protocol Support

Protocol validation and registry for extensible URI handling.

/**
 * Check if a protocol is supported
 * @param p - Protocol string to validate
 * @returns Type guard indicating if protocol is supported
 */
function isValidProtocol(p: string): p is keyof Protocols;

/**
 * Registry of supported protocol handlers
 */
const protocols: {
  data: GetUriProtocol<DataOptions>;
  file: GetUriProtocol<FileOptions>;
  ftp: GetUriProtocol<FTPOptions>;
  http: GetUriProtocol<HttpOptions>;
  https: GetUriProtocol<HttpOptions>;
};

Protocol Handlers

Caching and Error Handling

Built-in cache validation and error handling for efficient resource management.

/**
 * Error thrown when resource is not found
 */
class NotFoundError extends Error {
  code: 'ENOTFOUND';
  constructor(message?: string);
}

/**
 * Error thrown when resource has not been modified since cache
 */
class NotModifiedError extends Error {
  code: 'ENOTMODIFIED';  
  constructor(message?: string);
}

/**
 * Error thrown for HTTP-level errors
 */
class HTTPError extends Error {
  code: string;
  statusCode: number;
  constructor(statusCode: number, message?: string);
}

Caching and Error Handling

Core Types

// Node.js built-in types (import from respective modules)
import { Readable } from 'stream';

/**
 * Generic protocol handler function type
 */
type GetUriProtocol<T> = (parsed: URL, opts?: T) => Promise<Readable>;

/**
 * Union type for all supported protocols
 */
type Protocols = typeof protocols;

/**
 * Mapped type for protocol-specific options
 */
type ProtocolsOptions = {
  [P in keyof Protocols]: NonNullable<Parameters<Protocols[P]>[1]>;
};

/**
 * Conditional type for getting protocol-specific options based on URI
 */
type ProtocolOpts<T> = {
  [P in keyof ProtocolsOptions]: Protocol<T> extends P
    ? ProtocolsOptions[P]
    : never;
}[keyof Protocols];