antlr4ng - npm Package Compare versions

Comparing version 1.0.4 to 1.0.5

package.json

 {
     "name": "antlr4ng",
-    "version": "1.0.4",
+    "version": "1.0.5",
     "type": "module",
@@ -27,2 +27,4 @@ "description": "Alternative JavaScript/TypeScript runtime for ANTLR4",
         "@types/node": "20.5.9",
+        "@typescript-eslint/eslint-plugin": "6.6.0",
+        "@typescript-eslint/parser": "6.6.0",
         "babel-loader": "9.1.3",
@@ -32,8 +34,6 @@ "c8": "8.0.1",
         "eslint": "8.48.0",
-        "eslint-webpack-plugin": "4.0.1",
-        "@typescript-eslint/eslint-plugin": "6.6.0",
-        "@typescript-eslint/parser": "6.6.0",
         "eslint-plugin-import": "2.28.1",
         "eslint-plugin-jsdoc": "46.5.1",
         "eslint-plugin-prefer-arrow": "1.2.3",
+        "eslint-webpack-plugin": "4.0.1",
         "glob-parent": "6.0.2",
@@ -45,2 +45,3 @@ "jasmine": "5.1.0",
         "terser-webpack-plugin": "5.3.9",
+        "ts-node": "10.9.1",
         "typescript": "5.2.2",
@@ -54,3 +55,5 @@ "webpack": "5.88.2",
         "coverage": "c8 jasmine",
-        "lint": "eslint src/antlr4/"
+        "lint": "eslint src/antlr4/",
+        "generate-test-parser": "java -jar antlr/antlr4-4.13.2-SNAPSHOT-complete.jar -Dlanguage=TypeScript -o spec/benchmarks/generated -visitor -listener -Xexact-output-dir spec/benchmarks/MySQLLexer.g4 spec/benchmarks/MySQLParser.g4",
+        "benchmarks": "npm run build && node --no-warnings=ExperimentalWarning --loader ts-node/esm spec/benchmarks/run-benchmarks.ts"
     },
@@ -57,0 +60,0 @@ "engines": {

ReadMe.md

@@ -18,10 +18,31 @@ # JavaScript + TypeScript Target Runtime for ANTLR 4
 
-It is a drop-in replacement of the `antlr4` package, and can be used as such. For more information about ANTLR see www.antlr.org. More details about the JavaScript/TypeScript target can be found [here](https://github.com/antlr/antlr4/blob/master/doc/javascript-target.md).
+It is (mostly) a drop-in replacement of the `antlr4` package, and can be used as such. For more information about ANTLR see www.antlr.org. Read more details about the [JavaScript](https://github.com/antlr/antlr4/blob/master/doc/javascript-target.md) and [TypeScript](https://github.com/antlr/antlr4/blob/master/doc/typescript-target.md) targets at the provided links, but keep in mind that this documentation applies to the original JS/TS target.
 
+## Benchmarks
+
+This runtime is constantly monitored for performance regressions. The following table shows the results of the benchmarks run on last release:
+
+| Test | Cold Run | Warm Run|
+| ---- | -------- | ------- |
+| Query Collection| 8585 ms | 227 ms |
+| Example File | 1052 ms | 108 ms |
+| Large Inserts | 10417 ms | 10534 ms |
+| Total | 20114 ms | 10890 ms |
+
+The benchmarks consist of a set of query files, which are parsed by a MySQL parser.
+
 ## Release Notes
 
-### 1.0.2
+### 1.0.5
+
+- Added benchmarks.
+- Introduced the `IntStream` interface as the base for `CharStream` and `TokenStream`. This avoids duplicate code in the stream type definitions.
+- Removed `FileStream` as a preparation to get rid of the separate package files for node and browser. If something needs to be loaded from a file, the particular environment should provide the code for that.
+
+### 1.0.2 - 1.0.4
+
 - Github build action
 - Updated package.json
-- Exported `ErrorNode`
+- Exported `ErrorNode`, `InputMismatchException`
+- Some smaller fixes
 
@@ -32,3 +53,3 @@ ### 1.0.1
 - Removed all individual default exports. Only the final lib exports contain both, default and non-default exports. This avoids namespace access like `antlr4.atn`. Everything is available under a top level import.
-- Renamed ErrorListener to BaseListener, as that is what it is actually when comparing it to the Java runtime.
+- Renamed ErrorListener to BaseErrorListener, as that is what it is actually when comparing it to the Java runtime.
 
@@ -35,0 +56,0 @@ ### 1.0.0

src/antlr4/BufferedTokenStream.d.ts

@@ -10,23 +10,131 @@ /*
 import { Token } from "./Token.js";
+import type { CommonTokenStream } from "./CommonTokenStream.js";
+import { Interval } from "./misc/Interval.js";
 
-export declare class BufferedTokenStream extends TokenStream {
-    public readonly tokens: Token[];
-    public readonly fetchedEOF: boolean;
+/**
+ * This implementation of {@link TokenStream} loads tokens from a
+ * {@link TokenSource} on-demand, and places the tokens in a buffer to provide
+ * access to any previous token by index.
+ *
+ * <p>
+ * This token stream ignores the value of {@link Token#getChannel}. If your
+ * parser requires the token stream filter tokens to only those on a particular
+ * channel, such as {@link Token#DEFAULT_CHANNEL} or
+ * {@link Token#HIDDEN_CHANNEL}, use a filtering token stream such a
+ * {@link CommonTokenStream}.</p>
+ */
+export declare class BufferedTokenStream implements TokenStream {
+    /**
+     * The {@link TokenSource} from which tokens for this stream are fetched.
+     */
+    protected tokenSource: TokenSource;
 
+    /**
+     * A collection of all tokens fetched from the token source. The list is
+     * considered a complete view of the input once {@link #fetchedEOF} is set
+     * to {@code true}.
+     */
+    protected tokens: Token[];
+
+    /**
+     * Indicates whether the {@link Token#EOF} token has been fetched from
+     * {@link #tokenSource} and added to {@link #tokens}. This field improves
+     * performance for the following cases:
+     *
+     * <ul>
+     * <li>{@link #consume}: The lookahead check in {@link #consume} to prevent
+     * consuming the EOF symbol is optimized by checking the values of
+     * {@link #fetchedEOF} and {@link #p} instead of calling {@link #LA}.</li>
+     * <li>{@link #fetch}: The check to prevent adding multiple EOF symbols into
+     * {@link #tokens} is trivial with this field.</li>
+     * <ul>
+     */
+    protected fetchedEOF: boolean;
+
+    public constructor(tokenSource: TokenSource);
+
+    public getTokenSource(): TokenSource;
+
     public mark(): number;
     public release(marker: number): void;
+
     public reset(): void;
     public seek(index: number): void;
+
+    public get size(): number;
+    public get index(): number;
+
     public consume(): void;
+    public sync(i: number): number;
     public fetch(n: number): void;
-    public sync(i: number): number;
 
-    public getTokens(start?: number, stop?: number, types?: Set<number>): Token[];
+    public get(i: number): Token;
+    public get(start: number, stop: number): Token[];
+
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    public LA(i: number): number;
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    public LT(k: number): Token;
+
+    /** Reset this token stream by setting its token source. */
     public setTokenSource(tokenSource: TokenSource): void;
-    public nextTokenOnChannel(i: number, channel: number): number;
-    public previousTokenOnChannel(i: number, channel: number): number;
-    public filterForChannel(left: number, right: number, channel: number): number;
+
+    /**
+     * Given a start and stop index, return a List of all tokens in
+     *  the token type BitSet.  Return null if no tokens were found.  This
+     *  method looks at both on and off channel tokens.
+     */
+    public getTokens(): Token[];
+    public getTokens(start: number, stop: number): Token[];
+    public getTokens(start: number, stop: number, types: Set<number>): Token[];
+
+    /**
+     * Collect all tokens on specified channel to the right of
+     *  the current token up until we see a token on DEFAULT_TOKEN_CHANNEL or
+     *  EOF. If channel is -1, find any non default channel token.
+     */
+    public hiddenTokensToRight(tokenIndex: number): Token[];
+    public hiddenTokensToRight(tokenIndex: number, channel: number): Token[];
+
+    /**
+     * Collect all tokens on specified channel to the left of
+     *  the current token up until we see a token on DEFAULT_TOKEN_CHANNEL.
+     *  If channel is -1, find any non default channel token.
+     */
+    public hiddenTokensToLeft(tokenIndex: number): Token[];
+    public hiddenTokensToLeft(tokenIndex: number, channel: number): Token[];
+
     public getSourceName(): string;
 
+    /** Get all tokens from lexer until EOF */
     public fill(): void;
+
+    public getText(): string;
+    public getText(interval: Interval): string;
+
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    protected LB(k: number): Token;
+
+    /**
+     * Given a starting index, return the index of the next token on channel.
+     * Return {@code i} if {@code tokens[i]} is on channel. Return the index of
+     * the EOF token if there are no tokens on channel between {@code i} and
+     * EOF.
+     */
+    protected nextTokenOnChannel(i: number, channel: number): number;
+
+    /**
+     * Given a starting index, return the index of the previous token on
+     * channel. Return {@code i} if {@code tokens[i]} is on channel. Return -1
+     * if there are no tokens on channel between {@code i} and 0.
+     *
+     * <p>
+     * If {@code i} specifies an index at or after the EOF token, the EOF token
+     * index is returned. This is due to the fact that the EOF token is treated
+     * as though it were on every channel.</p>
+     */
+    protected previousTokenOnChannel(i: number, channel: number): number;
+
+    protected filterForChannel(left: number, right: number, channel: number): number;
+
 }

src/antlr4/CharStream.d.ts

@@ -7,19 +7,32 @@ /*
 
-export declare class CharStream {
-    public index: number; // defined as property
-    public size: number;// defined as property
+import { IntStream } from "./IntStream.js";
+import { Interval } from "./misc/Interval.js";
 
-    public constructor(data: string);
-    public constructor(data: string, decodeToUnicodeCodePoints: boolean);
-    public reset(): void;
-    public consume(): void;
-    // eslint-disable-next-line @typescript-eslint/naming-convention
-    public LA(offset: number): number;
-    // eslint-disable-next-line @typescript-eslint/naming-convention
-    public LT(offset: number): number;
-    public mark(): number;
-    public release(marker: number): void;
-    public seek(index: number): void;
-    public getText(start: number, stop: number): string;
-    public toString(): string;
+/**
+ * A source of characters for an ANTLR lexer.
+ *
+ * Note: CharStream is an interface in Java, but uses the CharStream class in JavaScript.
+ */
+export declare interface CharStream extends IntStream {
+    /**
+     * This method returns the text for a range of characters within this input
+     * stream. This method is guaranteed to not throw an exception if the
+     * specified {@code interval} lies entirely within a marked range. For more
+     * information about marked ranges, see {@link IntStream#mark}.
+     *
+     * @param interval an interval within the stream
+     * @returns the text of the specified interval
+     *
+     * @throws NullPointerException if {@code interval} is {@code null}
+     * @throws IllegalArgumentException if {@code interval.a < 0}, or if
+     * {@code interval.b < interval.a - 1}, or if {@code interval.b} lies at or
+     * past the end of the stream
+     * @throws UnsupportedOperationException if the stream does not support
+     * getting the text of the specified interval
+     */
+    getText(interval: Interval): string;
+    getText(start: number, stop: number): string;
+
+    reset(): void;
+    toString(): string;
 }

src/antlr4/index.d.ts

@@ -8,3 +8,2 @@ /*
 export * from "./InputStream.js";
-export * from "./FileStream.js";
 export * from "./CharStream.js";
@@ -24,2 +23,3 @@ export * from "./CharStreams.js";
 export * from "./Vocabulary.js";
+export * from "./IntStream.js";
 
@@ -26,0 +26,0 @@ export * from "./atn/index.js";

src/antlr4/Lexer.d.ts

@@ -35,2 +35,3 @@ /*
     public column: number;
+
     public _channel: number;
@@ -46,2 +47,4 @@ public _token: Token | null;
 
+    protected _modeStack: number[];
+
     public constructor(input: CharStream);
@@ -48,0 +51,0 @@

src/antlr4/TokenStream.d.ts

@@ -7,2 +7,3 @@ /*
 
+import { IntStream } from "./IntStream.js";
 import { Token } from "./Token.js";
@@ -12,18 +13,81 @@ import { TokenSource } from "./TokenSource.js";
 
-export declare class TokenStream {
-    public tokenSource: TokenSource;
-    public index: number;
-    public get size(): number;
-
+/**
+ * An IntStream whose symbols are {@link Token} instances.
+ */
+export declare interface TokenStream extends IntStream {
+    /**
+     * Get the {@link Token} instance associated with the value returned by
+     * {@link #LA LA(k)}. This method has the same pre- and post-conditions as
+     * {@link IntStream#LA}. In addition, when the preconditions of this method
+     * are met, the return value is non-null and the value of
+     * {@code LT(k).getType()==LA(k)}.
+     *
+     * @see IntStream#LA
+     */
     // eslint-disable-next-line @typescript-eslint/naming-convention
-    public LA(i: number): number;
-    // eslint-disable-next-line @typescript-eslint/naming-convention
-    public LT(k: number): Token;
-    public getText(interval?: Interval): string;
+    LT(k: number): Token;
 
-    // channelIndex can be retrieved using: lexer.channelNames().findIndex(channelName)
+    /**
+     * Gets the {@link Token} at the specified {@code index} in the stream. When
+     * the preconditions of this method are met, the return value is non-null.
+     *
+     * <p>The preconditions for this method are the same as the preconditions of
+     * {@link IntStream#seek}. If the behavior of {@code seek(index)} is
+     * unspecified for the current state and given {@code index}, then the
+     * behavior of this method is also unspecified.</p>
+     *
+     * <p>The symbol referred to by {@code index} differs from {@code seek()} only
+     * in the case of filtering streams where {@code index} lies before the end
+     * of the stream. Unlike {@code seek()}, this method does not adjust
+     * {@code index} to point to a non-ignored symbol.</p>
+     *
+     * @throws IllegalArgumentException if {code index} is less than 0
+     * @throws UnsupportedOperationException if the stream does not support
+     * retrieving the token at the specified index
+     */
+    get(index: number): Token;
 
-    public getHiddenTokensToLeft(tokenIndex: number, channelIndex?: number): Token[];
-    public getHiddenTokensToRight(tokenIndex: number, channelIndex?: number): Token[];
-    public get(idx: number): Token;
+    /**
+     * Gets the underlying {@link TokenSource} which provides tokens for this
+     * stream.
+     */
+    getTokenSource(): TokenSource;
+
+    /**
+     * Return the text of all tokens within the specified {@code interval}. This
+     * method behaves like the following code (including potential exceptions
+     * for violating preconditions of {@link #get}, but may be optimized by the
+     * specific implementation.
+     *
+     * <pre>
+     * TokenStream stream = ...;
+     * String text = "";
+     * for (int i = interval.a; i &lt;= interval.b; i++) {
+     *   text += stream.get(i).getText();
+     * }
+     * </pre>
+     *
+     * @param interval The interval of tokens within this stream to get text
+     * for.
+     * @returns The text of all tokens within the specified interval in this
+     * stream.
+     *
+     * @throws NullPointerException if {@code interval} is {@code null}
+     */
+    getText(interval: Interval): string;
+
+    /**
+     * Return the text of all tokens in the stream. This method behaves like the
+     * following code, including potential exceptions from the calls to
+     * {@link IntStream#size} and {@link #getText(Interval)}, but may be
+     * optimized by the specific implementation.
+     *
+     * <pre>
+     * TokenStream stream = ...;
+     * String text = stream.getText(new Interval(0, stream.size()));
+     * </pre>
+     *
+     * @returns The text of all tokens in the stream.
+     */
+    getText(): string;
 }

Fixed alerts

Debug access

Supply chain risk

Uses debug, reflection and dynamic code execution features.

Found 1 instance in 1 package

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

Minified code

Quality

This package contains minified code. This may be harmless in some cases where minified code is included in packaged libraries, however packages on npm should not minify code.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

5695449

increased by60.93%

Number of package files

109

increased by0.93%

Lines of code

4308

increased by9.01%

Number of low quality alerts

0

decreased by-100%

Number of lines in readme file

57

increased by58.33%

Number of low supply chain risk alerts

1

decreased by-66.67%

Worsened metrics

Dev dependency count

24

increased by4.35%

No dependency changes