postgres-range

library1.1.4jsnpmunverified

This library provides parsing and serialization capabilities for PostgreSQL's native range data types. It allows developers to convert PostgreSQL range strings (e.g., `[0,5)`) into a rich `Range` object with methods for querying properties like boundedness and inclusivity, and for performing operations such as point and range containment checks. The current stable version is 1.1.4. Releases appear to be driven by feature additions and bug fixes rather than a strict time-based cadence, as indicated by the recent v1.1.4 update addressing type definitions and adding a `toPostgres` method. Its key differentiator is its focused utility on PostgreSQL's specific range string format, providing a dedicated `Range` object API rather than a general-purpose interval library.

database serialization

npm install postgres-range

github ↗package ↗

INSTALL

IMPORT

SIG · POSTGRES-RANGE

postgres-range

databasejavascriptv1.1.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse, serialize, Range

✓ import { parse, serialize, Range, RANGE_LB_INC, RANGE_UB_INC } from 'postgres-range';

✗ import postgresRange from 'postgres-range';

The library primarily uses named exports for its core functions and `Range` class. `RANGE_LB_INC` and `RANGE_UB_INC` are constants for serialization.

postgresRange (CommonJS)

✓ const postgresRange = require('postgres-range');

✗ import postgresRange from 'postgres-range';

For CommonJS environments, the entire module is exported as an object containing `parse`, `serialize`, `Range`, and related constants.

Range (type)

✓ import type { Range } from 'postgres-range';

✗ import { Range } from 'postgres-range'; // Used only as a type

To import the `Range` class solely as a type in TypeScript, use the `import type` syntax to prevent it from being bundled as a value.

This quickstart demonstrates parsing various PostgreSQL range strings, checking their properties and contents, and serializing a `Range` object back into a string, including custom boundary types.

import { parse, serialize, Range, RANGE_LB_INC, RANGE_UB_INC } from 'postgres-range'; // Parse a half-open integer range from a string const intRange = parse('[0,5)', (value) => parseInt(value, 10)); console.log(`Range: [${intRange.lower}, ${intRange.upper})`); console.log(`Is bounded: ${intRange.isBounded()}`); console.log(`Lower bound closed: ${intRange.isLowerBoundClosed()}`); console.log(`Upper bound closed: ${intRange.isUpperBoundClosed()}`); console.log(`Contains point 4: ${intRange.containsPoint(4)}`); // Parse a nested range for containment check const subRange = parse('[1,2]', (value) => parseInt(value, 10)); console.log(`Contains sub-range [1,2]: ${intRange.containsRange(subRange)}`); // Parse an empty range const emptyRange = parse('empty'); console.log(`Is empty range: ${emptyRange.isEmpty()}`); // Serialize a custom range with both bounds inclusive const customRange = new Range(10, 20, RANGE_LB_INC | RANGE_UB_INC); // Represents [10,20] console.log(`Serialized custom range [10,20]: ${serialize(customRange)}`); // Example with floating point numbers const floatRange = parse('(0.5, 9.9]', parseFloat); console.log(`Float range: (${floatRange.lower}, ${floatRange.upper}]`); console.log(`Contains point 7.2: ${floatRange.containsPoint(7.2)}`);

Debug

Known issues

gotchaParsing ranges requires a `transform` function if the range values are not simple strings or require specific type coercion (e.g., to integers, dates, floats). Forgetting this will result in bounds being `string` type by default.

fix

Always provide a `transform` function to `parse()` that converts the bound values to the desired type, e.g., `(value) => parseInt(value, 10)` or `(value) => new Date(value)`.

affects: >=1.0.0

gotchaThe `serialize` function does not automatically infer the range type (inclusive/exclusive) from the `Range` object's internal representation if it was constructed directly without `parse`. You must explicitly provide boundary flags like `RANGE_LB_INC` and `RANGE_UB_INC`.

fix

When creating a `Range` object manually with `new Range(lower, upper, flags)`, ensure `flags` are set correctly using `RANGE_LB_INC` and `RANGE_UB_INC` bitmasks if you intend for `serialize` to produce the expected output.

affects: >=1.0.0

breakingPrior to v1.1.4, TypeScript type definitions were incomplete or incorrect for some methods, specifically regarding the return types and `toPostgres` method availability.

fix

Update to `postgres-range@1.1.4` or newer to get accurate and complete TypeScript definitions, especially if using the `toPostgres` method or relying on method return types for type safety.

affects: <1.1.4

Errors

Common errors & fixes

Argument of type 'number' is not assignable to parameter of type 'string'.

Attempting to pass a number directly to `parse` without explicit type handling in the `transform` function.

fix

Ensure the input to `parse` is a string and provide a `transform` function: `parse('[1,5]', (value) => parseInt(value, 10))`.

TypeError: range.containsPoint is not a function

Trying to call `Range` object methods on a raw string or an incorrectly constructed object that is not an instance of `Range`.

fix

Ensure the range object is created using `parse()` or `new Range()` from the `postgres-range` library before calling its methods.

SyntaxError: Unexpected token 'export'

ReferenceError: require is not defined

Attempting to use ES module `import` syntax in a CommonJS context, or `require` in an ES module context.

fix

For CommonJS environments, use `const { parse } = require('postgres-range');`. For ES module environments, ensure your `package.json` has `"type": "module"` and use `import { parse } from 'postgres-range';`.

Upgrade

Version history

1.1.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/martianboy/postgres-range ↗

packagehttps://www.npmjs.com/package/postgres-range ↗