https://github.com/blend/ts-selector
A typescript implementation of Kubernetes label selectors.
https://github.com/blend/ts-selector
kubernetes selectors
Last synced: about 1 month ago
JSON representation
A typescript implementation of Kubernetes label selectors.
- Host: GitHub
- URL: https://github.com/blend/ts-selector
- Owner: blend
- License: mit
- Created: 2020-12-03T01:09:16.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2023-03-16T16:26:43.000Z (about 2 years ago)
- Last Synced: 2025-03-26T15:54:51.992Z (about 2 months ago)
- Topics: kubernetes, selectors
- Language: TypeScript
- Homepage:
- Size: 335 KB
- Stars: 1
- Watchers: 5
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# ts-selector
`ts-selector` is an implementation of Kubernetes label selectors in typescript.
It enables you to parse selectors and match labels (`Record`) against them.
The compilation process uses finite state machines and is relatively efficient, but it is best practice to hold a reference for a selector and run many matches through it.
Selectors are compiled as predicate trees such that once you compile the selector it is every fast to evaluate label matches.
## Installation
```bash
> npm i ts-selector
```
## Usage
```typescript
import * as selector from "ts-selector"
const mySelector = "x in (foo,,baz),y,z notin ()";
const sel = selector.mustParse(mySelector); // throws an exception on error
console.log(sel.matches({ x: "foo", y: "bar" }); // prints 'true';
console.log(sel.matches({ x: "baz", y: "bar" }); // prints 'true';
console.log(sel.matches({ x: "not-foo", y: "bar" }); // prints 'false';
// you can also verify labels are conformant
console.log(selector.checkLabels({ x: "foo", y: "bar" })) // prints 'null';
console.log(selector.checkLabels({ "_bad": "foo", y: "bar" })) // prints 'Error: ...';
console.log(selector.mustCheckLabels({ "_bad": "foo", y: "bar" })) // throws an exception
```
## Nomenclature note
This package has two modes of handling errors; checked errors (i.e. errors as values) and exceptions.
Methods that start with `must...` will throw exceptions.
## Selector Grammar
```
Selectors must be in the form:
::= | ","
::= [!] KEY [ | ]
::= "" |
::= |
::= "notin"
::= "in"
::= "(" ")"
::= VALUE | VALUE ","
::= ["="|"=="|"!="] VALUE
KEY is a sequence of one or more characters following: [ DNS_SUBDOMAIN "/" ] DNS_LABEL.
- DNS_SUBDOMAIN is a sequence of one or more characters ([a-z0-9-.]), and must start and end with an alphanumeric ([a-z0-9]).
Symbol characters ('.', '-') cannot repeat. Max length is 253 characters.
- DNS_LABEL is a sequence of one or more characters ([A-Za-z0-9_-.]). Max length is 63 characters.
VALUE is a sequence of zero or more characters ([A-Za-z0-9_-.]). Values must start and end with an alphanumeric ([a-z0-9A-Z]). Max length is 63 characters.
Delimiter is white space: (' ', '\t')
Example of valid syntax:
"x in (foo,,baz),y,z notin ()"
Note:
(1) Inclusion - " in " - denotes that the KEY exists and is equal to any of the
VALUEs in its requirement
(2) Exclusion - " notin " - denotes that the KEY is not equal to any
of the VALUEs in its requirement or does not exist
(3) The empty string is a valid VALUE
(4) A requirement with just a KEY - as in "y" above - denotes that
the KEY exists and can be any VALUE.
(5) A requirement with just !KEY requires that the KEY not exist.
```
# Contributions
Issues are highly appreciated.
We welcome contributions but might be slow to respond to PRs. Please allow a week or so for a review for any pull requests.
# License
`ts-selector` is licensed under the MIT license.