diffusion
Version:
Diffusion JavaScript client
242 lines (241 loc) • 9.6 kB
JavaScript
;
/**
* @module diffusion.selectors
*/
var __read = (this && this.__read) || function (o, n) {
var m = typeof Symbol === "function" && o[Symbol.iterator];
if (!m) return o;
var i = m.call(o), r, ar = [], e;
try {
while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
}
catch (error) { e = { error: error }; }
finally {
try {
if (r && !r.done && (m = i["return"])) m.call(i);
}
finally { if (e) throw e.error; }
}
return ar;
};
var __spreadArray = (this && this.__spreadArray) || function (to, from) {
for (var i = 0, il = from.length, j = to.length; i < il; i++, j++)
to[j] = from[i];
return to;
};
Object.defineProperty(exports, "__esModule", { value: true });
exports.TopicSelectors = void 0;
var topic_selector_parser_1 = require("./../internal/topics/topic-selector-parser");
var topic_selector_1 = require("./topic-selector");
/**
* Create {@link TopicSelector} instances for use with other API methods.
*
* Selectors are evaluated against topic paths. A topic path is a '/'
* separated string of parts, which map to the topic tree. Each part is
* formed of one or more UTF characters, except '/'. Topic paths are absolute,
* and evaluated from the root of the topic tree.
*
* **Example:**
* ```
* // Create a topic selector
* var selector = diffusion.selectors.parse('?foo/bar/.*');
* ```
*/
var TopicSelectors = /** @class */ (function () {
function TopicSelectors() {
/**
* The Prefix enum
*/ // eslint-disable-next-line @typescript-eslint/naming-convention
this.Prefix = topic_selector_1.Prefix;
/**
* The Type enum
*/ // eslint-disable-next-line @typescript-eslint/naming-convention
this.Type = topic_selector_1.Type;
}
/**
* Parse an expression to create a selector.
*
* The following types of expression are supported. The type is determined
* by the first character of the expression.
*
* <dl>
* <dt>Path
* <dd>Path expressions begin with the character <code>></code>. The remainder of
* the expression must be a valid topic path. A topic path is a '/'
* separated string of parts. Each part is formed of one or more UTF
* characters, except '/'.
* <p>
* A {@link Type.PATH PATH} selector is returned that only
* selects the topic with the given path.
* </p>
* <p>
* The initial <code>></code> can be omitted if the path begins with a character
* other than one of <code>#</code>, <code>?</code>, <code>></code>,
* <code>*</code>, <code>$</code>, <code>%</code>, <code>&</code>, or
* <code><</code>. This abbreviated syntax allows most
* topic paths to be used directly as selector expressions which appears
* more natural. Abbreviated path expressions are converted to standard path
* expressions by prepending the <code>></code> character. Thus
* <code>a/b</code> is interpreted as <code>>a/b</code>.
* <p>
* <code>Diffusion.topicSelectors().parse("a/b").getExpression()</code> will
* return <code>">a/b"</code>.
*
* <dt>Split-path pattern
* <dd>Split-path pattern expressions begin with the character <code>?</code>.
* The remainder of the expression is split into a list of regular
* expressions using the <code>/</code> character as a separator.
*
* <p>
* A {@link Type.SPLIT_PATH_PATTERN SPLIT_PATH_PATTERN}
* selector is returned that selects topics for which each regular
* expression matches each part of the topic path at the corresponding
* level.
* </p>
*
* <dt>Full-path pattern
* <dd>Full-path pattern expressions begin with the character <code>*</code>.
* The remainder of the pattern is a regular expression.
*
* <p>
* A {@link Type.FULL_PATH_PATTERN FULL_PATH_PATTERN} selector
* is returned that selects topics for which the regular expression matches
* the complete topic path.
* </p>
*
* <p>
* Full-path patterns provide a lot of expressive power but should be used
* sparingly since the server can evaluate split-path patterns more
* efficiently.
*
* <p>
* Selector sets are the preferred way to combine expressions.
* <code>anyOf("a", "b")</code> is equivalent to the full-path expression "
* <code>*</code> <code>/a|/b</code>", but can be evaluated more efficiently by the
* server.
*
* <dt>Selector set
* <dd>Selector set expressions begin with the character <code>#</code>. The
* remainder of the expression is a list of contained selectors, formatted
* as described below.
*
* A {@link Type.SELECTOR_SET SELECTOR_SET} selector is
* returned that selects topics that match any of the contained selectors.
*
* The contained selectors are formatted as follows. First, any selector sets
* are expanded to produce a full list of non-selector set expressions. Then
* the selector expressions are concatenated, separated by the separator
* <code>////</code>. This separator has been chosen as it is not valid in a
* path, and is not a useful sequence in a pattern.
* </dl>
*
* <h2>Descendant pattern qualifiers</h2>
*
* Split-path and full-path pattern expressions can be further modified by
* appending <code>/</code> or <code>//</code>. These control the behavior of the
* selector with respect to the descendants of the topics that match the
* pattern.
*
* <ul>
*
* <li>If the expression does not end with <code>/</code> or <code>//</code>, it
* selects only the topics that match the pattern.</li>
*
* <li>If the expression ends with <code>/</code>, it selects only the
* descendants of the matching topics, excluding the matching topics.</li>
*
* <li>If the expression ends with <code>//</code>, it selects the matching
* topics and all of their descendants.</li>
* </ul>
*
* <h2>Regular expressions</h2>
*
* <p>
* Any Java-style regular expression can be used in
* split-path and full-path patterns, with the following restrictions:
*
* <ul>
* <li>A regular expression may not be empty.
* <li>A regular expression used in split-path patterns may not contain the
* path separator <code>/</code>.
* <li>A regular expression used in full-path patterns may not contain the
* selector set separator <code>////</code> .
* </ul>
*
* <p>
* Regular expressions that break any of these restrictions would never
* match a topic path, so they make no practical difference.
* </p>
*
*
* <h2>Examples</h2>
*
* <h3>Path expressions</h3>
*
* Path | Matches `alpha/beta`? | Matches `alpha/beta/gamma`?
* ------------- | ---------------------- | ---------------------------
* `>alpha/beta` | yes | no
* `alpha/beta` | yes | no
* `>alpha/beta/gamma` | no | yes
* `alpha/beta/gamma` | no | yes
* `>beta` | no | no
* `beta` | no | no
* `>.*``/.*` | no | no
* `>/alpha/beta/` | yes | no
* `/alpha/beta/` | yes | no
*
* <h3>Split-path pattern expressions</h3>
*
* Path | Matches `alpha/beta`? | Matches `alpha/beta/gamma`?
* ------------- | ---------------------- | ---------------------------
* `?alpha/beta` | yes | no
* `?alpha/beta/gamma` | no | yes
* `?beta` | no | no
* `?.*` | no | no
* `?.*``/.*` | yes | no
* `?alpha/beta/` | no | yes
* `?alpha/beta//` | yes | yes
* `?alpha/.*``//` | yes | yes
*
* <h3>Full-path pattern expressions</h3>
*
* Path | Matches `alpha/beta`? | Matches `alpha/beta/gamma`?
* ------------- | ---------------------- | ---------------------------
* `*alpha/beta` | yes | no
* `*alpha/beta/gamma` | no | yes
* `*beta` | no | no
* `*.*beta` | yes | no
* `*.*` | yes | yes
* `*alpha/beta/` | no | yes
* `*alpha/beta//` | yes | yes
*
* **Example:**
* ```
* // Simple selector
* var selector = diffusion.selectors.parse(">a/b");
* ```
*
* **Example:**
* ```
* // Creating a selector set
* var selectorSet = diffusion.selectors.parse(">a", ">b");
* ```
*
* @param expression the pattern expression(s). At least one
* valid selector has to be specified.
* @param args additional pattern expressions
* @return the topic selector. If multiple expressions are provided,
* this will return a `SELECTOR_SET` that will match if
* any of the * provided `selectors` match.
* @throws an {@link IllegalArgumentError} if the expression could not be parsed
*/
TopicSelectors.prototype.parse = function (expression) {
var args = [];
for (var _i = 1; _i < arguments.length; _i++) {
args[_i - 1] = arguments[_i];
}
return topic_selector_parser_1.parseSelector.apply(void 0, __spreadArray([expression], __read(args)));
};
return TopicSelectors;
}());
exports.TopicSelectors = TopicSelectors;