api

API Docs

Welcome to @safelytyped/url!

• Introduction
  • What Is A Safe Type?
  • Why Use Safe Types?
  • Why A URL Type?
• Our Goals
  • Our Design Criteria

Introduction

What Is A Safe Type?

A safe type is a type that can only ever hold legal values.

For example, URL is a safe type because it can only ever hold a valid URL (although we don't guarantee that it points to anywhere useful!)

Why Use Safe Types?

If your function accepts a safe type, your function doesn't need to do its own defensive programming for robustness.

Safe types do the defensive programming for you.

On top of that, we build our safe types using written coding standards.

Why A URL Type?

You might be wondering why you should use our URL, instead of the built-in NodeJS URL. Here's a few reasons why:

• No side-effects:

  The built-in NodeJS URL is a read-write object. When you modify it, you've no idea whether or not other parts of your code hold a reference to it. That can lead to unwanted surprises and side-effects.

  Our URL is a read-only object. Yes, even the URL search parameters object is disconnected from the URL it came from. This ensures that there are zero surprises, and zero side-effects.

• Extra features:

  Our URL includes some extra APIs for making easy modifications to the URL.

  • Use our URL.resolve() as an all-in-one URL modder. (It returns a new URL object, so it doesn't violate the first reason to use our URL!)
  • Keep track of where your URL came from through the handy URL.base property. Perfect for working through and resolving reference entries in an OpenAPI spec or JSON schema.

• A means to deliver functionality into business logic:

  If you pass typed values into your business logic, it can call methods on those types without having to know whether it's working with a Filepath or a URL.

  Value objects can implement protocols (interfaces that describe behaviours). And business logic can consume and use objects based solely on their protocols, without caring whether they're a Filepath or a URL.

• Runtime extensibility:

  Along with protocols, value objects can be augmented at runtime with extensions. You don't have to submit a pull request to our repo and wait for us to merge it; you can create your own extension and use it locally straight away.

Our Goals

The purpose of this library is to give us the smallest possible, safest URL safe type that adds value to our code.

Our Design Criteria

There's a couple of things that we wanted out of URL.

• URL must be a safer version of NodeJS's URL class.
• URL's API should be very familiar to anyone who already knows NodeJS's URL class, and NodeJS's path module.
• URL should be useful for tracking a data location: a path that's built from a mix of a base path and a location relative to that base path.