@ismail-elkorchi/css-parser 0.1.1 → 0.2.0

package/dist/public/parse.d.ts

@@ -0,0 +1,37 @@
+import type { CommaSeparatedComponentValuesResult, ComponentValue, ComponentValuesResult, CssBlockItem, CssDeclaration, CssRule, CssStylesheet, SyntaxResult } from "../internal/syntax/ast.js";
+import type { SyntaxParserOptions } from "../internal/syntax/parser.js";
+import type { TokenizationResult } from "../internal/syntax/tokens.js";
+import type { TokenizerOptions } from "../internal/syntax/tokenizer.js";
+import type { DecodedTokenizationResult, DecodedSyntaxResult, ParseStylesheetBytesOptions, ParseStylesheetStreamOptions, TokenizeBytesOptions, TokenizeStreamOptions } from "./types.js";
+/** Thrown when a byte stream violates the public input contract or fails. */
+export declare class CssStreamError extends Error {
+    readonly reason: "invalid-chunk" | "read-failed";
+    readonly code = "CSS_STREAM_ERROR";
+    constructor(reason: "invalid-chunk" | "read-failed", cause?: unknown);
+}
+/** Parses a complete CSS stylesheet. */
+export declare function parseStylesheet(input: string, options?: SyntaxParserOptions): SyntaxResult<CssStylesheet>;
+/** Parses a list of stylesheet rules. */
+export declare function parseStylesheetContents(input: string, options?: SyntaxParserOptions): SyntaxResult<readonly CssRule[]>;
+/** Parses declarations and nested rules from a block's contents. */
+export declare function parseBlockContents(input: string, options?: SyntaxParserOptions): SyntaxResult<readonly CssBlockItem[]>;
+/** Parses exactly one CSS rule. */
+export declare function parseRule(input: string, options?: SyntaxParserOptions): SyntaxResult<CssRule>;
+/** Parses one CSS declaration. */
+export declare function parseDeclaration(input: string, options?: SyntaxParserOptions): SyntaxResult<CssDeclaration>;
+/** Parses exactly one CSS component value. */
+export declare function parseComponentValue(input: string, options?: SyntaxParserOptions): SyntaxResult<ComponentValue>;
+/** Parses a list of CSS component values. */
+export declare function parseComponentValues(input: string, options?: SyntaxParserOptions): ComponentValuesResult;
+/** Parses comma-separated lists of CSS component values. */
+export declare function parseCommaSeparatedComponentValues(input: string, options?: SyntaxParserOptions): CommaSeparatedComponentValuesResult;
+/** Tokenizes a complete CSS string. */
+export declare function tokenize(input: string, options?: TokenizerOptions): TokenizationResult;
+/** Decodes and parses a complete CSS stylesheet byte array. */
+export declare function parseStylesheetBytes(bytes: Uint8Array, options?: ParseStylesheetBytesOptions): DecodedSyntaxResult<CssStylesheet>;
+/** Reads, decodes, and parses a complete CSS stylesheet byte stream. */
+export declare function parseStylesheetStream(stream: ReadableStream<Uint8Array>, options?: ParseStylesheetStreamOptions): Promise<DecodedSyntaxResult<CssStylesheet>>;
+/** Decodes and tokenizes a complete CSS byte array. */
+export declare function tokenizeBytes(bytes: Uint8Array, options?: TokenizeBytesOptions): DecodedTokenizationResult;
+/** Reads, decodes, and tokenizes a complete CSS byte stream. */
+export declare function tokenizeStream(stream: ReadableStream<Uint8Array>, options?: TokenizeStreamOptions): Promise<DecodedTokenizationResult>;

package/dist/public/parse.js

@@ -0,0 +1,298 @@
+import { CssEncodingSniffer, decodeCssBytes } from "../internal/syntax/encoding.js";
+import { parseCssBlockContents, parseCssCommaSeparatedComponentValues, parseCssComponentValue, parseCssComponentValues, parseCssDeclaration, parseCssRule, parseCssStylesheet, parseCssStylesheetContents } from "../internal/syntax/parser.js";
+import { ResourceGuard, SyntaxAbortError } from "../internal/syntax/resources.js";
+import { tokenizeCss } from "../internal/syntax/tokenizer.js";
+/** Thrown when a byte stream violates the public input contract or fails. */
+export class CssStreamError extends Error {
+    reason;
+    code = "CSS_STREAM_ERROR";
+    constructor(reason, cause) {
+        super(reason === "invalid-chunk"
+            ? "CSS byte streams must yield Uint8Array chunks"
+            : "Unable to read the CSS byte stream", cause === undefined ? undefined : { cause });
+        this.reason = reason;
+        this.name = "CssStreamError";
+    }
+}
+function assertInput(input) {
+    if (typeof input !== "string") {
+        throw new TypeError("input must be a string");
+    }
+}
+function assertOptions(options) {
+    if (options === null ||
+        typeof options !== "object" ||
+        Array.isArray(options)) {
+        throw new TypeError("options must be an object");
+    }
+}
+/** Parses a complete CSS stylesheet. */
+export function parseStylesheet(input, options = {}) {
+    assertInput(input);
+    assertOptions(options);
+    return parseCssStylesheet(input, options);
+}
+/** Parses a list of stylesheet rules. */
+export function parseStylesheetContents(input, options = {}) {
+    assertInput(input);
+    assertOptions(options);
+    return parseCssStylesheetContents(input, options);
+}
+/** Parses declarations and nested rules from a block's contents. */
+export function parseBlockContents(input, options = {}) {
+    assertInput(input);
+    assertOptions(options);
+    return parseCssBlockContents(input, options);
+}
+/** Parses exactly one CSS rule. */
+export function parseRule(input, options = {}) {
+    assertInput(input);
+    assertOptions(options);
+    return parseCssRule(input, options);
+}
+/** Parses one CSS declaration. */
+export function parseDeclaration(input, options = {}) {
+    assertInput(input);
+    assertOptions(options);
+    return parseCssDeclaration(input, options);
+}
+/** Parses exactly one CSS component value. */
+export function parseComponentValue(input, options = {}) {
+    assertInput(input);
+    assertOptions(options);
+    return parseCssComponentValue(input, options);
+}
+/** Parses a list of CSS component values. */
+export function parseComponentValues(input, options = {}) {
+    assertInput(input);
+    assertOptions(options);
+    return parseCssComponentValues(input, options);
+}
+/** Parses comma-separated lists of CSS component values. */
+export function parseCommaSeparatedComponentValues(input, options = {}) {
+    assertInput(input);
+    assertOptions(options);
+    return parseCssCommaSeparatedComponentValues(input, options);
+}
+/** Tokenizes a complete CSS string. */
+export function tokenize(input, options = {}) {
+    assertInput(input);
+    assertOptions(options);
+    return tokenizeCss(input, options);
+}
+function encodingOptions(options) {
+    return {
+        ...(options.transportEncodingLabel === undefined
+            ? {}
+            : { transportEncodingLabel: options.transportEncodingLabel }),
+        ...(options.environmentEncodingLabel === undefined
+            ? {}
+            : { environmentEncodingLabel: options.environmentEncodingLabel }),
+        ...(options.defaultEncodingLabel === undefined
+            ? {}
+            : { defaultEncodingLabel: options.defaultEncodingLabel }),
+        ...(options.maxCharsetBytes === undefined
+            ? {}
+            : { maxCharsetBytes: options.maxCharsetBytes })
+    };
+}
+function processingLimits(limits) {
+    if (limits === undefined)
+        return {};
+    return {
+        ...(limits.maxTokens === undefined ? {} : { maxTokens: limits.maxTokens }),
+        ...(limits.maxNodes === undefined ? {} : { maxNodes: limits.maxNodes }),
+        ...(limits.maxDepth === undefined ? {} : { maxDepth: limits.maxDepth }),
+        ...(limits.maxSteps === undefined ? {} : { maxSteps: limits.maxSteps })
+    };
+}
+function mergeUsage(usage, inputBytes, maxBufferedBytes) {
+    return Object.freeze({
+        ...usage,
+        inputBytes,
+        maxBufferedBytes: Math.max(usage.maxBufferedBytes, maxBufferedBytes)
+    });
+}
+function withEncoding(result, decision, inputBytes, maxBufferedBytes) {
+    return Object.freeze({
+        ...result,
+        usage: mergeUsage(result.usage, inputBytes, maxBufferedBytes),
+        encoding: decision
+    });
+}
+function combine(chunks, length) {
+    const bytes = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
+async function decodeStream(stream, options) {
+    const input = stream;
+    if (input === null ||
+        typeof input !== "object" ||
+        !("getReader" in input) ||
+        typeof input.getReader !== "function") {
+        throw new TypeError("stream must be a readable byte stream");
+    }
+    const guard = new ResourceGuard({
+        ...(options.limits?.maxInputBytes === undefined
+            ? {}
+            : { maxInputBytes: options.limits.maxInputBytes }),
+        ...(options.limits?.maxBufferedBytes === undefined
+            ? {}
+            : { maxBufferedBytes: options.limits.maxBufferedBytes })
+    }, options.signal);
+    const sniffer = new CssEncodingSniffer(encodingOptions(options));
+    const reader = stream.getReader();
+    const pending = [];
+    const decoded = [];
+    let pendingBytes = 0;
+    let totalBytes = 0;
+    let decoder = null;
+    let decision = null;
+    try {
+        for (;;) {
+            guard.assertActive();
+            let item;
+            try {
+                item = await reader.read();
+            }
+            catch (error) {
+                throw new CssStreamError("read-failed", error);
+            }
+            guard.assertActive();
+            if (item.done)
+                break;
+            if (!(item.value instanceof Uint8Array)) {
+                throw new CssStreamError("invalid-chunk");
+            }
+            totalBytes += item.value.byteLength;
+            guard.setInputBytes(totalBytes);
+            if (decision === null) {
+                pending.push(item.value);
+                pendingBytes += item.value.byteLength;
+                guard.observeBufferedBytes(pendingBytes);
+                decision = sniffer.write(item.value);
+                if (decision !== null) {
+                    decoder = new TextDecoder(decision.encoding);
+                    const text = decoder.decode(combine(pending, pendingBytes), {
+                        stream: true
+                    });
+                    if (text.length > 0)
+                        decoded.push(text);
+                    pending.length = 0;
+                    pendingBytes = 0;
+                }
+            }
+            else {
+                const text = decoder?.decode(item.value, { stream: true }) ?? "";
+                if (text.length > 0)
+                    decoded.push(text);
+            }
+        }
+        if (decision === null) {
+            decision = sniffer.finish();
+            decoder = new TextDecoder(decision.encoding);
+            const text = decoder.decode(combine(pending, pendingBytes), {
+                stream: true
+            });
+            if (text.length > 0)
+                decoded.push(text);
+        }
+        const tail = decoder?.decode() ?? "";
+        if (tail.length > 0)
+            decoded.push(tail);
+        const usage = guard.snapshot();
+        return Object.freeze({
+            text: decoded.join(""),
+            decision,
+            inputBytes: totalBytes,
+            maxBufferedBytes: usage.maxBufferedBytes
+        });
+    }
+    catch (error) {
+        try {
+            await reader.cancel(error);
+        }
+        catch {
+            // Cancellation is best effort after the primary failure.
+        }
+        if (options.signal?.aborted === true && !(error instanceof SyntaxAbortError)) {
+            throw new SyntaxAbortError(options.signal.reason);
+        }
+        throw error;
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+function assertBytes(bytes) {
+    if (!(bytes instanceof Uint8Array)) {
+        throw new TypeError("bytes must be a Uint8Array");
+    }
+}
+/** Decodes and parses a complete CSS stylesheet byte array. */
+export function parseStylesheetBytes(bytes, options = {}) {
+    assertBytes(bytes);
+    assertOptions(options);
+    const guard = new ResourceGuard({
+        ...(options.limits?.maxInputBytes === undefined
+            ? {}
+            : { maxInputBytes: options.limits.maxInputBytes })
+    }, options.signal);
+    guard.setInputBytes(bytes.byteLength);
+    const decoded = decodeCssBytes(bytes, encodingOptions(options));
+    const result = parseCssStylesheet(decoded.text, {
+        limits: processingLimits(options.limits),
+        ...(options.signal === undefined ? {} : { signal: options.signal })
+    });
+    return withEncoding(result, decoded.decision, bytes.byteLength, 0);
+}
+/** Reads, decodes, and parses a complete CSS stylesheet byte stream. */
+export async function parseStylesheetStream(stream, options = {}) {
+    assertOptions(options);
+    const decoded = await decodeStream(stream, options);
+    const result = parseCssStylesheet(decoded.text, {
+        limits: processingLimits(options.limits),
+        ...(options.signal === undefined ? {} : { signal: options.signal })
+    });
+    return withEncoding(result, decoded.decision, decoded.inputBytes, decoded.maxBufferedBytes);
+}
+/** Decodes and tokenizes a complete CSS byte array. */
+export function tokenizeBytes(bytes, options = {}) {
+    assertBytes(bytes);
+    assertOptions(options);
+    const guard = new ResourceGuard({
+        ...(options.limits?.maxInputBytes === undefined
+            ? {}
+            : { maxInputBytes: options.limits.maxInputBytes })
+    }, options.signal);
+    guard.setInputBytes(bytes.byteLength);
+    const decoded = decodeCssBytes(bytes, encodingOptions(options));
+    const result = tokenizeCss(decoded.text, {
+        limits: processingLimits(options.limits),
+        ...(options.signal === undefined ? {} : { signal: options.signal })
+    });
+    return Object.freeze({
+        ...result,
+        usage: mergeUsage(result.usage, bytes.byteLength, 0),
+        encoding: decoded.decision
+    });
+}
+/** Reads, decodes, and tokenizes a complete CSS byte stream. */
+export async function tokenizeStream(stream, options = {}) {
+    assertOptions(options);
+    const decoded = await decodeStream(stream, options);
+    const result = tokenizeCss(decoded.text, {
+        limits: processingLimits(options.limits),
+        ...(options.signal === undefined ? {} : { signal: options.signal })
+    });
+    return Object.freeze({
+        ...result,
+        usage: mergeUsage(result.usage, decoded.inputBytes, decoded.maxBufferedBytes),
+        encoding: decoded.decision
+    });
+}

package/dist/public/traversal.d.ts

@@ -0,0 +1,13 @@
+import type { CssAstNode, CssAstNodeOfKind, CssNodeVisitor } from "./types.js";
+/** Thrown when traversal receives a cyclic or shared syntax graph. */
+export declare class CssTreeStructureError extends TypeError {
+    readonly reason: "cycle" | "shared-node";
+    readonly code = "CSS_INVALID_TREE";
+    constructor(reason: "cycle" | "shared-node");
+}
+/** Visits every structural node in deterministic depth-first order. */
+export declare function walkCss(root: CssAstNode, visitor: CssNodeVisitor): void;
+/** Finds a structural node by its tree-local identifier. */
+export declare function findNodeById(root: CssAstNode, id: number): CssAstNode | null;
+/** Returns structural nodes with an exact `kind` discriminator. */
+export declare function findNodesByKind<K extends CssAstNode["kind"]>(root: CssAstNode, kind: K): readonly CssAstNodeOfKind<K>[];

package/dist/public/traversal.js

@@ -0,0 +1,96 @@
+/** Thrown when traversal receives a cyclic or shared syntax graph. */
+export class CssTreeStructureError extends TypeError {
+    reason;
+    code = "CSS_INVALID_TREE";
+    constructor(reason) {
+        super(reason === "cycle"
+            ? "CSS syntax trees cannot contain cycles"
+            : "CSS syntax trees cannot contain shared structural nodes");
+        this.reason = reason;
+        this.name = "CssTreeStructureError";
+    }
+}
+function structuralValues(values) {
+    return values.filter((value) => value.kind === "function-block" || value.kind === "simple-block");
+}
+function childNodes(node) {
+    switch (node.kind) {
+        case "stylesheet":
+            return node.rules;
+        case "at-rule":
+            return [
+                ...structuralValues(node.prelude),
+                ...(node.block === null ? [] : [node.block])
+            ];
+        case "qualified-rule":
+            return [...structuralValues(node.prelude), node.block];
+        case "block":
+            return node.items;
+        case "declaration":
+        case "function-block":
+        case "simple-block":
+            return structuralValues(node.value);
+    }
+}
+/** Visits every structural node in deterministic depth-first order. */
+export function walkCss(root, visitor) {
+    const active = new WeakSet();
+    const seen = new WeakSet();
+    const stack = [{
+            node: root,
+            parent: null,
+            depth: 0,
+            leaving: false
+        }];
+    while (stack.length > 0) {
+        const frame = stack.pop();
+        if (frame === undefined)
+            continue;
+        if (frame.leaving) {
+            active.delete(frame.node);
+            continue;
+        }
+        if (active.has(frame.node))
+            throw new CssTreeStructureError("cycle");
+        if (seen.has(frame.node))
+            throw new CssTreeStructureError("shared-node");
+        active.add(frame.node);
+        seen.add(frame.node);
+        visitor(frame.node, frame.depth, frame.parent);
+        stack.push({ ...frame, leaving: true });
+        const children = childNodes(frame.node);
+        for (let index = children.length - 1; index >= 0; index -= 1) {
+            const child = children[index];
+            if (child !== undefined) {
+                stack.push({
+                    node: child,
+                    parent: frame.node,
+                    depth: frame.depth + 1,
+                    leaving: false
+                });
+            }
+        }
+    }
+}
+/** Finds a structural node by its tree-local identifier. */
+export function findNodeById(root, id) {
+    if (!Number.isSafeInteger(id) || id <= 0) {
+        throw new RangeError("id must be a positive safe integer");
+    }
+    let found = null;
+    walkCss(root, (node) => {
+        if (found === null && node.id === id)
+            found = node;
+    });
+    return found;
+}
+/** Returns structural nodes with an exact `kind` discriminator. */
+export function findNodesByKind(root, kind) {
+    const found = [];
+    walkCss(root, (node) => {
+        if (node.kind === kind) {
+            found.push(node);
+        }
+    });
+    return Object.freeze(found);
+}