Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/armanozak/snq
A utility function to avoid type errors when traversing over arrays and object properties.
https://github.com/armanozak/snq
elvis-operator exception-handling null-coalescing-operator null-conditional-operator null-safety optional-chaining safe-navigation type-error typescript
Last synced: 16 days ago
JSON representation
A utility function to avoid type errors when traversing over arrays and object properties.
- Host: GitHub
- URL: https://github.com/armanozak/snq
- Owner: armanozak
- License: mit
- Created: 2019-04-20T22:44:49.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-03-02T21:39:09.000Z (over 1 year ago)
- Last Synced: 2024-09-19T11:39:49.477Z (about 2 months ago)
- Topics: elvis-operator, exception-handling, null-coalescing-operator, null-conditional-operator, null-safety, optional-chaining, safe-navigation, type-error, typescript
- Language: TypeScript
- Homepage: https://stackblitz.com/edit/snq
- Size: 1.05 MB
- Stars: 30
- Watchers: 1
- Forks: 3
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# snq (Safe Navigation Query)
[](https://bundlephobia.com/result?p=snq)
[](./LICENSE)
[](https://twitter.com/armanozak)
> Now that [optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining) and [nullish coalescing](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Nullish_coalescing_operator) operators are available, libraries like snq have become redundant. Please use them instead.
**snq** is a utility function to safely navigate arrays and object properties without getting type errors. It is **not an original idea at all** and is actually adapted and only slightly different from [idx](https://github.com/facebookincubator/idx). The main differences are as follows:
- snq returns `undefined` whenever a `TypeError` happens, regardless of the reason for the error and throws an error only if it is not a `TypeError`. idx returns `null`, if the cause of the error is a `null` value and throws an error if the error is not caused by an `undefined` or `null` value.
- snq has an optional second parameter which works as **default value** to return instead of `undefined`.
- idx requires the source object as a first parameter. snq does not.
- idx has a Babel plugin for replacing idx instances with conventional traversing in order to improve performance. Although it is not benchmarked yet, due to lack of reason checks, it is safe to say that snq is faster than idx. Thus, a Babel plugin could prove insignificant for snq.
- snq is written in TypeScript and, unlike idx, it does not support Flow types.
## Installation
Run the following code in your terminal:
```shell
yarn add snq
```
or if you are using npm:
```shell
npm install --save snq
```
## Setup
```typescript
import snq from 'snq';
```
## Usage
Consider the following interfaces as `products` list:
```typescript
interface Price {
amount: number;
currency: string;
symbol?: string;
}
interface Product {
id: number;
name: string;
inStock: boolean;
price?: {
final: Price;
original?: Price;
};
}
```
This is how it would probably look like when you want to get original price symbol of first product:
```typescript
products.length &&
products[0].price &&
products[0].price.original &&
products[0].price.original.symbol;
```
Otherwise, you will get a type error. Using `snq`, it is safe to write the following:
```typescript
const symbol = snq(() => products[0].price.original.symbol);
// symbol is undefined if a type error happens, actual value if not
```
There is an optional second argument which represents the default value to return when a type error happens.
```typescript
const symbol = snq(() => products[0].price.original.symbol, '$');
// symbol is "$" if a type error happens, actual value if not
```
The type of the symbol returned will be inferred as string in both cases.
Check the [demo application](https://stackblitz.com/edit/snq) out.