als-document 0.12.0 → 1.0.0-beta

package/readme.md

@@ -1,204 +1,273 @@
-# Als-Document
+# als-document: HTML Parser & DOM Manipulation Library
 
-*If something wrong or not working properly, please write me to: sh.mashkanta@gmail.com*
+## Overview
 
+`als-document` is a powerful library for parsing HTML and manipulating the DOM structure on backend and frontend. It provides a robust and intuitive API for querying and interacting with DOM elements using selectors, making it a valuable tool for web developers.
 
-Document is a class which gets html as string and return new object with DOM tree. 
-You can add or remove elements from DOM tree and modify each element. 
-You can select elements and collections and read and modify them with given instruments. 
+## Release notes
+* als-document is still on alpha testing. All tested features works fine, but through the use, discovering  some bugs or things that should work different. For example in this release, changed the way for storing attributes with empty value. 
+* Also, this release, has additional very powefull feature which is building cache for storing DOM tree as json and building back DOM from cache. 
 
-**0.11**
-* events issue fixed
 
-**0.12**
-* added getAttribute and setAttribute
+## Installation
 
-## Write and Read files
-Document have 2 static methods to read and write files. 
-The syntax:
-```javascript
-Document.writeFile(filePath,obj,encoding = 'utf-8')
-Document.readFile(filePath,encoding = 'utf-8')
+To install the `als-document` library, use the following npm command:
+
+```bash
+npm i als-document
 ```
 
-* ``filepath`` - filepath can be string (absolute path to file) or array for joining.
-* ``obj`` - obj can be string or object for stringify.
-* ``encoding`` - encoding for read or write file
 
-Example:
+## Including the Library
+
+The library provides three different files to cater to different module systems:
+
+1. **index.js**: This file uses the CommonJS module system. It's suitable for projects using Node.js or bundlers like Browserify or Webpack. The entry point in `package.json` for this file is "main".
+
 ```javascript
-let {Document} = require('als-document')
-let html = Document.readFile([__dirname,'index.html'])
+const { parseHTML, Node, Query, TextNode, SingleNode,Root } = require('als-document');
 ```
 
+2. **index.mjs**: This file uses the ES Modules (ESM) system. It's suitable for modern JavaScript environments that support ESM. The entry point in `package.json` for this file is "module".
 
-## Creating new object
+```js
+import { parseHTML, Node, Query, TextNode, SingleNode, Root } from 'als-document';
+```
 
-Document constructor get single string parameter - the outerHTML for converting to virtual DOM tree. 
+3. **document.js**: By including this file, a constant variable named `alsDocument` is created, which wraps all the exports.
 
-```javascript
-let document = new Document(html) // html has to be string
-document.domTree // includes virtual DOM tree as array of elements
+```html
+<script src="/node_modules/als-document/document.js"></script>
+<script>
+   const { parseHTML, Node, Query, TextNode, SingleNode, buildFromCache, cacheDoc, Root } = alsDocument
+</script>
 ```
 
+## parseHTML
 
-## QuerySelector for single element
-Then document object has created, you can select elements or collections. 
-For selecting single element, use ``$(selector)`` and for selecting collections ``$$(selector)``.
+`parseHTML` is a function that takes an HTML string and constructs a DOM tree representation from it. It recognizes various HTML elements, such as comments, scripts, styles, and CDATA, and organizes them into nodes that can be manipulated and queried.
 
-**Selecting element**
+### API:
+`parseHTML(html: string) -> Node`
 
-```javascript
-document.$('div') // select first div in document
-document.$('div.some') // select first div element with some class
-```
+Parses an HTML string and returns a tree structure representing its content.
 
-At this time, selector supports this:
-* Selects all elements - ``*``
-* element - ``div``
-* class - ``.some-class``
-* id - ``#some-id``
-* parent - ``div > p``
-* next - ``div + p``
-* previous - ``p ~ ul``
-* attribute - ``[some-attribute="some value"]``
-   * ``[prop]``
-   * ``[prop~=value]``
-   * ``[prop|=value]``
-   * ``[prop^="value"]``
-   * ``[prop$="value"]``
-   * ``[prop*="value"]``
+* `html`: The HTML string to parse.
+* `Returns`: A Node object representing the root of the parsed HTML content tree.
 
+###  Expected Outcome:
+When using the parseHTML function, the output will be a tree of nodes representing the HTML content. Each node can be one of the following:
+* **Node**: A standard HTML element node with tag name, attributes, and child nodes.
+* **SingleNode**: Represents self-closing or void HTML elements.
+* **TextNode**: Represents text content in the HTML.
 
-The folowing, **won't work**: ``div p``.
+Each node will have a tag name, a dictionary of attributes, and a list of child nodes (if applicable).
 
+### Examples
 
-Each returned element, has the folowing:
-```javascript
-{
-   parent, // parent element
-   prev, // previous element (null if no exists)
-   next, // next element (null if no exists)
-   innerText, // innner text of element and it's childNodes separated by |
-   children, // array of childNodes(elements and text nodes) - includes text element too
-   tagName, // tag name of element
-   id, // id of element if exists (not included in attributes)
-   attributes, // object of attributes (id not included)
-   classList, // array of classes and add and remove methods
-   getAttribute(name)
-   setAttribute(name,value)
-   $(selector),
-   $$(selector),
-   json(), // remove all methods and circular objects from object
-   remove(), // remove this element
-   add(element/outerHtml,place), 
-   add0(element/outerHtml), 
-   add1(element/outerHtml), 
-   add2(element/outerHtml), 
-   add3(element/outerHtml), 
-}
-```
+```js
+const parsedHTML = parseHTML('<div class="container"><img src="image.jpg" alt="Image"/><p>Hello, world!</p></div>');
 
-Text node has the folowing:
-```javascript
-{
-   text,
-   prev,
-   next
-}
+// The returned `parsedHTML` object will be a tree-like structure. 
+// For instance, parsedHTML.childNodes[0] would represent the <div> element, 
+// and parsedHTML.childNodes[0].childNodes[0] would represent the <img> element inside it.
 ```
 
-Comment node:
-```javascript
-tagName:comment,
-comment // comment it self
-```
+```js
+const parsedScript = parseHTML('<script>console.log("Hello, world!");</script>');
 
-You can add or remove classes with classList methods.
-Example:
-```javascript
-let element = document.$('div')
-element.classList.remove('some')
-element.classList.add('another')
-element.classList.add('onemore')
+// The returned `parsedScript` object will contain a `script` Node with a child node 
+// holding the JavaScript code as text content.
 ```
 
-Also you can change element's id:
-```javascript
-let element = document.$('div')
-element.id = 'new-id'
-```
+Remember, the actual tree structure will be more complex and detailed, but the provided examples give you a basic understanding of how to navigate through the parsed result.
 
-## Element methods
+## Node
 
-```javascript
-json() // remove all methods and circular objects from object
-remove() // remove this element
-add(element/outerHtml,place) // adding AdjacentHTML or AdjacentElement to place(0-3)
-add0(element/outerHtml) // adding AdjacentHTML or AdjacentElement beforebegin
-add1(element/outerHtml) // adding AdjacentHTML or AdjacentElement afterbegin
-add2(element/outerHtml) // adding AdjacentHTML or AdjacentElement beforeend
-add3(element/outerHtml) // adding AdjacentHTML or AdjacentElement afterend
-```
+`Node` is a fundamental class that represents an element node in the DOM tree. It provides functionality similar to the native DOM API in browsers, but with its own implementation.
 
-Example:
-```javascript
-let document = new Document(html)
-let a = document.$('a')
-let div = document.$('div')
-div.add2('<div id="test">Hello world</div>')
-div.add3(a)
-a.remove()
-```
+### Properties:
+- **tagName**: Represents the tag name of the element.
+- **attributes**: A dictionary of attributes and their values.
+- **childNodes**: An array of child nodes for the element.
+- **isSingle**: Boolean value to check if the node is a self-closing tag.
+- **parentNode, previousElementSibling, nextElementSibling, children**: Navigation properties to move through the DOM tree.
+- **dataset, classList, style**: Special properties for interacting with `data-*` attributes, classes, and inline styles.
 
+### Methods:
+- **getAttribute, setAttribute, removeAttribute**: Manipulate element's attributes.
+- **remove**: Removes the element from its parent.
+- **innerHTML, outerHTML**: Get and set the inner or entire HTML of the element.
+- **querySelector, querySelectorAll**: Find elements within the node based on CSS-like selectors.
+  - limits: pseudo selector like `:first-of-type` or `:checked` not available
+  - namaspace for tags `some:namspace` available
+  - there are additional methods `$` for `querySelector` and `$$` for `querySelectorAll`
+- **getElementsByClassName, getElementsByTagName, getElementById**: Get elements by class, tag, or id respectively.
+- **insertAdjacentElement, insertAdjacentHTML, insertAdjacentText**: Insert content relative to the element.
+- **appendChild**: Add a child node to the element.
+- **insert(place,element)**: place (0-3) or beforebegin,afterbegin,... eleemnt - raw html or element
 
-Create new element with ``Document.newElement(outerHtml)``
 
-```javascript
-Document.newElement('<div id="test">Hello world</div>')
-```
+### SingleNode
+
+`SingleNode` extends from the `Node` class and represents elements that don't have closing tags (self-closing tags) in HTML. Examples include `<img>`, `<br>`, and `<!DOCTYPE>`. This class has restricted methods and properties since these elements can't have child nodes.
+
+### TextNode
+
+`TextNode` is a class that represents text content within the DOM. A TextNode holds raw text data and does not have child nodes.
+
+
+### Root node (extends Node)
 
+Has additional getters and setters:
+  * getter root.title
+  * setter root.title
+  * getter root.body
+  * getter root.head
 
-## QuerySelector for Collection ``$$()``
-To select few elements, use ``$$(selector)`` method. 
+
+
+### Examples:
 
 ```javascript
-document.$$('div') // return collection of all div elements
+const div = new Node('div');
+div.setAttribute('class', 'container');
+
+const img = new SingleNode('img', { src: 'image.jpg', alt: 'An image' });
+div.appendChild(img);
+
+console.log(div.outerHTML);  // Outputs: <div class="container"><img src="image.jpg" alt="An image"></div>
+
+const p = new Node('p',{},div); // adding as last child to parent div
+p.textContent = "Hello, world!";
+
+const foundP = div.querySelector('p');
+console.log(foundP.textContent);  // Outputs: Hello, world!
 ```
 
-The collection is array which has the elements and two methods: ``each`` and ``parse``.
 
-``each`` method gets callback function with 3 parameters: element it self, index of the element in collection and collection itself. 
+## Query
+
+The `Query` class is designed to parse CSS selector strings and transform them into a structured object format, providing detailed insights into each selector and its components.
+
+By using the class, one can expect to transform a CSS selector string into an array of objects. 
+
+Each object will represent a selector, containing detailed information such as its tag, identifier, classes, attributes, and associated selectors if any. This can be useful for further processing or analysis of CSS selectors in an application.
+
+### Example 
 
-Here example:
 ```javascript
-let array = []
-document.$$('div').each((element,index,collection) => {
-   if(element.innerText.includes('some text'))
-      array.push(element)
-})
+let q1 = 'html>body>div.tabs~.some[type $= "radio and some"]>p+div>.some-id .tab-content~input[disabled] div.some'
+let result = new Query(q1).selectors
+let result1 = Query.get(q1)
+// result and result1 has to be same
+console.log(result)
 ```
 
-``parse`` method, gets two parameters: ``part`` and ``fn`` and return array with results. 
-* ``part`` is a part of element. It can be innerText, id, tagName or any property inside attributes. 
-* ``fn`` is a filter function which gets content of part. If return true, content will be included.
-
-Example:
+Result:
 ```javascript
-new Document(htmlText).$$('div')
-.parse('innerText',
-   content=> (content.length > 0) ? true : false)
+[
+   {
+      "query": "div.some",
+      "tag": "div",
+      "classList": [
+         "some"
+      ],
+      "ancestors": [
+         {
+            "query": ".some-id",
+            "classList": [
+               "some-id"
+            ],
+            "parents": [
+               {
+                  "query": "div",
+                  "tag": "div"
+               }
+            ],
+            "prev": {
+               "query": "p",
+               "tag": "p",
+               "parents": [
+                  {
+                     "query": ".some[0]",
+                     "classList": [
+                        "some"
+                     ],
+                     "attribs": [
+                        {
+                           check:(f),
+                           "query": "[type$=\"radio and some\"]",
+                           "name": "type",
+                           "value": "radio and some",
+                           "sign": "$="
+                        }
+                     ]
+                  }
+               ],
+               "prevAny": {
+                  "query": "div.tabs",
+                  "tag": "div",
+                  "classList": [
+                     "tabs"
+                  ],
+                  "parents": [
+                     {
+                        "query": "html",
+                        "tag": "html"
+                     },
+                     {
+                        "query": "body",
+                        "tag": "body"
+                     }
+                  ]
+               },
+               "group": "html>body>div.tabs~.some[0]>p"
+            },
+            "group": "html>body>div.tabs~.some[0]>p+div>.some-id"
+         },
+         {
+            "query": "input[1]",
+            "tag": "input",
+            "attribs": [
+               {
+                  "query": "[disabled]",
+                  "name": "disabled"
+               }
+            ],
+            "prevAny": {
+               "query": ".tab-content",
+               "classList": [
+                  "tab-content"
+               ]
+            },
+            "group": ".tab-content~input[1]"
+         }
+      ],
+      "group": "html>body>div.tabs~.some[type $= \"radio and some\"]>p+div>.some-id .tab-content~input[disabled] div.some"
+   }
+]
 ```
 
-## Building html
+### Attribs and check function
+if attribute has value, attrib object will contain check function with one parameter for value to check. 
 
-For building html again, use ``build`` method. 
-Example:
 ```javascript
-let element = document.$('div')
-element.classList.add('another')
-element.classList.remove('some')
-element.id = 'new-id'
-document.build() // return new html text
-document.build([__dirname,'new-index.html']) // will create a file with new html text
+let s = Query.get('[test^="some"]')[0]
+console.log(s.attribs[0].check('some value test')) // true
 ```
+
+## buildFromCache and cacheDoc
+
+Building DOM from raw html, usually takes tens of milliseconds. But now, you can build DOM once and save it's cache as regular stringified JSON. 
+The caching process and building from cache takes less then 5ms for each and require realy low resources. 
+
+
+How it works?
+```js
+const html = `` // some real html 255KB
+const root = parseHTML(html); // 31.9ms
+const cache = cacheDoc(root); // 2.4ms
+const root1 = buildFromCache(cache); // 1.2ms
+console.log(root.inneHTML === root1.innerHTML) // true
+```

package/src/build.js

@@ -0,0 +1,66 @@
+const { readFileSync, writeFileSync, watchFile, watch } = require('fs')
+const { join,basename } = require('path')
+
+function optimizeCode(content) {
+   // content = content.replace(/(?<!\\)\/\/.*$/gm, '') // remove comments
+   content = content.replace(/^(?<!\\)\/\/.*$|(?<=\s)(?<!\\)\/\/.*$/gm, '') // remove comments
+   // content = content.replace(/\;\s*?$/gm,'') // remove ; at end of line
+   content = content.replace(/\[\s*?\n\s*/gm, '[') // 
+   content = content.replace(/\s*?\]/gm, ']') // 
+   content = content.replace(/\s*?$/gm, '') // remove space at end of line
+   content = content.replace(/^\s\s\s/gm, '  ') // change tripple space to double space
+   content = content.replace(/\s(\=|\>|\<|\-|\+|\*|\!)/g, (s) => s.trim()) // replace space before operators
+   content = content.replace(/(\=|\>|\-|\+|\*)\s/g, (s) => s.includes(' ') ? s.trim() : s) // replace space after operators
+   content = content.replace(/\,\s*?$\s*/gm, ',') // join lines separated with comma
+   content = content.replace(/\s?,\s?/g, ',') // trim comma
+   content = content.replace(/\s\{/g, '{')
+   return content
+}
+
+const root = join(__dirname, '..')
+const files = {
+   'query': ['query','check-element'],
+   'node':[
+      'dataset','find','text-node',
+      'style','class-list','node','single-node','root'
+   ],
+   'parse':['parse-atts','void-tags','parser','cache'],
+}
+const fileList = []
+function buildFileList() {
+   Object.entries(files).forEach(([dir,filenames]) => {
+      filenames.forEach(filename => {
+         fileList.push(join(__dirname,dir,filename+'.js'))
+      });
+   });
+}
+
+buildFileList()
+
+function build() {
+   let content = fileList.map(filePath => readFileSync(filePath, 'utf-8')).join('\n');
+
+   const toReturn = '{ parseHTML, Node, Query, TextNode, SingleNode, buildFromCache, cacheDoc, Root }'
+   content = optimizeCode(content)
+   writeFileSync(join(root, 'document.js'), `const alsDocument = (function(){\n${content}\nreturn ${toReturn}\n})()`)
+   writeFileSync(join(root, 'index.js'), content + '\n' + `module.exports = ${toReturn}`)
+   writeFileSync(join(root, 'index.mjs'), content + '\n' + `export default ${toReturn}`)
+   console.log('Files are builded')
+}
+
+build()
+if (process.argv[2] === '--watch') {
+   let count = 1;
+   console.log('Waching...')
+   let lastChangeTime = Date.now()
+   Object.keys(files).forEach(dirName => {
+      const dirPath = join(__dirname,dirName)
+      watch(dirPath, (eventType, filename) => {
+         let newChangeTime = Date.now()
+         if(newChangeTime - lastChangeTime < 1000) return
+         build()
+         lastChangeTime = newChangeTime
+         console.log(`${filename} has changed (${count++})`)
+      });
+   })
+}

package/src/node/class-list.js

@@ -0,0 +1,25 @@
+class NodeClassList {
+   constructor(node) { this.node = node }
+   get classes() { return (this.node.attributes.class || "").split(" ").filter(Boolean) }
+   set classes(val) { this.node.attributes.class = val.join(" ") }
+   contains(className) { return this.classes.includes(className) }
+
+   add(className) {
+      const currentClasses = this.classes;
+      if (!currentClasses.includes(className)) this.classes = [...currentClasses, className];
+   }
+
+   remove(className) { this.classes = this.classes.filter(cls => cls !== className); }
+
+   toggle(className) {
+      if (this.classes.includes(className)) this.remove(className);
+      else this.add(className);
+   }
+
+   replace(oldClass, newClass) {
+      if (this.classes.includes(oldClass)) {
+         this.remove(oldClass);
+         this.add(newClass);
+      }
+   }
+}

package/src/node/dataset.js

@@ -0,0 +1,15 @@
+const getDataName = prop => 'data-' + prop.toLowerCase()
+function getDataset(element) {
+   return new Proxy(element.attributes, {
+       get: (target, prop) => {return target[getDataName(prop)]},
+       set: (target, prop, value) => {target[getDataName(prop)] = value; return true},
+       deleteProperty: (target, prop) => { // Удаляем data-* атрибут
+           const dataAttr = getDataName(prop)
+           if (dataAttr in target) {
+               delete target[dataAttr];
+               return true;  // обозначает успешное удаление
+           }
+           return false;
+       }
+   });
+}

package/src/node/find.js

@@ -0,0 +1,12 @@
+function find(selectors,element,collection,first=false,firstTime = true) {
+   for(let selector of selectors) {
+      if(checkElement(element,selector)) collection.add(element)
+   }
+   if(element.children)
+   element.children.forEach(child => {
+      if(first && collection.size > 0) return
+      find(selectors,child,collection,first,false)
+   })
+
+   return firstTime ? [...collection] : collection
+}