css-ast-parser 1.0.0

package/README.md

@@ -0,0 +1,118 @@
+# CSS AST Parser
+A fast and lightweight CSS parser with AST transformations and plugin-based architecture.
+The goal of this project is to provide high performance CSS processing with minimal overhead, suitable for large stylesheets and real time transformations.
+Built using: custom parser, generator and AST walker (tokenization stage was intentionally removed for improving performance)
+
+## Features
+Lightweight and fast parsing
+AST-based transformations
+Plugin system (similar to PostCSS/Babel)
+Safe node mutation (remove/replace during traversal)
+Single-line minified output
+Zero dependencies
+
+
+## Installation
+Clone the repository
+
+## Usage
+```js
+const fs = require("fs");
+
+const { parse } = require("./src/parser");
+const { generate } = require("./src/generator");
+const { walk } = require("./src/walker");
+
+const plugins = [
+    require("./plugins/removeBackground")
+];
+
+const css = fs.readFileSync("./input.css", "utf-8");
+
+const ast = parse(css);
+walk(ast, plugins);
+
+const out = generate(ast);
+fs.writeFileSync("./output.css", out);
+```
+
+
+
+## How It Works
+The processing pipeline:
+CSS -> parse() -> AST -> walk() -> generate() -> CSS
+parse -> converts CSS into AST
+walk -> applies plugins and mutates AST
+generate -> converts AST back to CSS
+
+
+
+## AST Structure
+Example node:
+```json
+{
+  "type": "decl",
+  "prop": "color",
+  "value": "red"
+}
+```
+
+Node types:
+rule - selector block
+decl - declaration
+atrule - @rules
+comment - comments
+
+
+
+## Plugins
+Plugins return visitors.
+
+### Example: remove background-color
+```js
+module.exports = function () {
+    return {
+        decl: {
+            enter(path) {
+                if (path.isDecl("background-color")) {
+                    path.remove();
+                }
+            }
+        }
+    };
+};
+```
+
+### Path API
+path.remove() — remove node
+path.replace(node) — replace node
+path.setProp(v) — change property
+path.setValue(v) — change value
+
+Helpers:
+path.isDecl(name)
+path.isRule(selector)
+path.isAtRule(name)
+
+
+
+## Transformation Pipeline
+1. Read CSS
+2. Parse AST
+3. Apply plugins
+4. Generate optimized CSS
+
+## Performance
+This project is optimized for speed and low memory usage.
+Key points:
+fast loops (no forEach/map)
+array join instead of string concat
+minimal allocations
+safe mutation traversal
+Designed to handle large CSS files efficiently.
+
+## Author
+DragonDragging
+
+## Contact
+If you find any bugs, please contact me on Discord with a detailed explanation: @dragondragging

package/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "css-ast-parser",
+  "version": "1.0.0",
+  "description": "Fast CSS parser with AST transformations",
+  "main": "src/index.js",
+  "author": "DragonDragging",
+  "license": "MIT"
+}

package/src/generator.js

@@ -0,0 +1,79 @@
+function generate(ast) {
+    const out = [];
+
+    function gen(nodes) {
+        for (let i = 0; i < nodes.length; i++) {
+            const n = nodes[i];
+
+            // CSS rule: selector { decls }
+            if (n.type === "rule") {
+                if (!n.selector) continue;
+
+                out.push(n.selector, "{");
+
+                const children = n.nodes;
+                if (children) {
+                    for (let j = 0; j < children.length; j++) {
+                        const d = children[j];
+
+                        // inline comment
+                        if (d.type === "comment") {
+                            out.push("/*", d.value, "*/");
+                        }
+                        // declaration
+                        else if (d.type === "decl") {
+                            out.push(d.prop, ":", d.value, ";");
+                        }
+                    }
+                }
+
+                out.push("}");
+            }
+
+            // @rule (media, property, etc.)
+            else if (n.type === "atrule") {
+                if (!n.name) continue;
+
+                out.push("@", n.name);
+
+                if (n.query) out.push(" ", n.query);
+
+                // no body (@import etc.)
+                if (!n.nodes) {
+                    out.push(";");
+                    continue;
+                }
+
+                out.push("{");
+
+                const children = n.nodes;
+                for (let j = 0; j < children.length; j++) {
+                    const d = children[j];
+
+                    if (d.type === "comment") {
+                        out.push("/*", d.value, "*/");
+                    }
+                    else if (d.type === "decl") {
+                        out.push(d.prop, ":", d.value, ";");
+                    }
+                    // nested rule / atrule
+                    else {
+                        gen([d]);
+                    }
+                }
+
+                out.push("}");
+            }
+
+            // comment
+            else if (n.type === "comment") {
+                out.push("/*", n.value, "*/");
+            }
+        }
+    }
+
+    gen(ast.nodes);
+    return out.join(""); // single allocation
+}
+
+module.exports = { generate };

package/src/index.js

@@ -0,0 +1,5 @@
+const { parse } = require("./parser");
+const { generate } = require("./generator");
+const { walk } = require("./walker");
+
+module.exports = { parse, generate, walk };

package/src/parser.js

@@ -0,0 +1,178 @@
+function parse(css) {
+    let i = 0;
+    const len = css.length;
+
+    // fast whitespace check
+    function isWS(c) {
+        return c === 32 || c === 10 || c === 9 || c === 13;
+    }
+
+    // skip whitespace
+    function skipWS() {
+        while (i < len && isWS(css.charCodeAt(i))) i++;
+    }
+
+    // read /* comment */
+    function readComment() {
+        i += 2;
+        let start = i;
+
+        while (i < len && !(css[i] === "*" && css[i + 1] === "/")) i++;
+
+        const value = css.slice(start, i).trim();
+        i += 2;
+
+        return { type: "comment", value };
+    }
+
+    // collapse whitespace
+    function clean(str) {
+        return str.replace(/\s+/g, " ").trim();
+    }
+
+    // read selector until {
+    function readSelector() {
+        let start = i;
+        while (i < len && css[i] !== "{") i++;
+        return clean(css.slice(start, i));
+    }
+
+    // read property name
+    function readProp() {
+        let start = i;
+        while (i < len && css[i] !== ":" && css[i] !== "}") i++;
+        return clean(css.slice(start, i));
+    }
+
+    // read value (supports functions like rgb())
+    function readValue() {
+        let start = i;
+        let depth = 0;
+
+        while (i < len) {
+            const c = css[i];
+
+            if (c === "(") depth++;
+            else if (c === ")") depth--;
+
+            if (depth === 0 && (c === ";" || c === "}")) break;
+
+            i++;
+        }
+
+        return clean(css.slice(start, i));
+    }
+
+    // parse declarations inside {}
+    function parseDecls() {
+        const nodes = [];
+
+        while (i < len) {
+            skipWS();
+            if (i >= len) break;
+
+            // end block
+            if (css[i] === "}") {
+                i++;
+                break;
+            }
+
+            // comment
+            if (css[i] === "/" && css[i + 1] === "*") {
+                nodes.push(readComment());
+                continue;
+            }
+
+            const prop = readProp();
+
+            if (css[i] === "}") {
+                i++;
+                break;
+            }
+
+            i++; // skip :
+
+            const value = readValue();
+            if (css[i] === ";") i++;
+
+            nodes.push({ type: "decl", prop, value });
+        }
+
+        return nodes;
+    }
+
+    // parse rules / atrules
+    function parseRules() {
+        const nodes = [];
+
+        // atrules with declarations instead of nested rules
+        const declAtrules = new Set(["property", "font-face", "page"]);
+
+        while (i < len) {
+            skipWS();
+            if (i >= len) break;
+
+            // end block
+            if (css[i] === "}") {
+                i++;
+                break;
+            }
+
+            // comment
+            if (css[i] === "/" && css[i + 1] === "*") {
+                nodes.push(readComment());
+                continue;
+            }
+
+            // @rule
+            if (css[i] === "@") {
+                i++;
+
+                let start = i;
+                while (i < len && !isWS(css.charCodeAt(i)) && css[i] !== "{" && css[i] !== ";") i++;
+                const name = css.slice(start, i);
+
+                skipWS();
+
+                let queryStart = i;
+                while (i < len && css[i] !== "{" && css[i] !== ";") i++;
+                const query = clean(css.slice(queryStart, i));
+
+                // no block
+                if (css[i] === ";") {
+                    i++;
+                    nodes.push({ type: "atrule", name, query, nodes: null });
+                    continue;
+                }
+
+                i++; // {
+
+                const children = declAtrules.has(name)
+                    ? parseDecls()
+                    : parseRules();
+
+                nodes.push({ type: "atrule", name, query, nodes: children });
+                continue;
+            }
+
+            // normal rule
+            const selector = readSelector();
+            i++; // {
+
+            nodes.push({
+                type: "rule",
+                selector,
+                nodes: parseDecls()
+            });
+        }
+
+        return nodes;
+    }
+
+    return {
+        type: "stylesheet",
+        nodes: parseRules()
+    };
+}
+
+module.exports = { parse };

package/src/walker.js

@@ -0,0 +1,96 @@
+function walk(ast, plugins = []) {
+    const visitors = plugins.map(p => p());
+    function createPath(node, parent, container, index) {
+        let removed = false;
+       
+        return {
+            node,
+            parent,
+            // remove current node safely
+            remove() {
+                if (!container) {
+                    return;
+                }
+                container.splice(index, 1);
+                removed = true;
+            },
+            // replace current node
+            replace(newNode) {
+                if (!container) {
+                    return;
+                }
+                container[index] = newNode;
+                this.node = newNode;
+            },
+            // mutate decl
+            setProp(v) {
+                if (node.type === "decl") {
+                    node.prop = v;
+                }
+            },
+            setValue(v) {
+                if (node.type === "decl") {
+                    node.value = v;
+                }
+            },
+            // helpers
+            isDecl(name) {
+                return node.type === "decl" && (!name || node.prop === name);
+            },
+            isRule(sel) {
+                return node.type === "rule" && (!sel || node.selector === sel);
+            },
+            isAtRule(name) {
+                return node.type === "atrule" && (!name || node.name === name);
+            },
+            // internal flag
+            removed: () => removed
+        };
+    }
+
+    function visit(node, parent, container, index) {
+        const path = createPath(node, parent, container, index);
+
+        // enter phase
+        for (let i = 0; i < visitors.length; i++) {
+            const v = visitors[i];
+            const fn = v[node.type];
+            if (fn && fn.enter) {
+                fn.enter(path);
+            }
+        }
+
+        // if removed in enter → stop
+        if (path.removed()) {
+            return;
+        }
+
+        // traverse children safely (handles mutations)
+        if (node.nodes && node.nodes.length) {
+            const list = node.nodes;
+            for (let i = 0; i < list.length;) {
+                const child = list[i];
+                visit(child, node, list, i);
+
+                // if current child removed don't increment
+                if (list[i] === child) {
+                    i++;
+                }
+            }
+        }
+
+        // exit phase
+        for (let i = 0; i < visitors.length; i++) {
+            const v = visitors[i];
+            const fn = v[node.type];
+            if (fn && fn.exit) {
+                fn.exit(path);
+            }
+        }
+    }
+    
+    visit(ast, null, null, null);
+}
+module.exports = {
+    walk
+};