@astrojs/compiler 0.11.3 → 0.12.0-next.1

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @astrojs/compiler
 
+## 0.12.0-next.1
+
+### Patch Changes
+
+- a539d53: Update exposed types
+
+## 0.12.0-next.0
+
+### Minor Changes
+
+- 8ce39c7: Do not render implicit tags created during the parsing process
+- 41b825a: Remove "as" option, treats all documents as fragments that generate no implicit tags
+- 483b34b: Add `parse` function which generates an AST
+- 9e5e2f8: Adds support for `Astro.self` (as accepted in the [Recursive Components RFC](https://github.com/withastro/rfcs/blob/main/active-rfcs/0000-recursive-components.md)).
+
+### Patch Changes
+
+- 16b167c: Expose AST types via `@astrojs/compiler/types`
+
+## 0.11.4
+
+### Patch Changes
+
+- 99b5de2: Reset tokenizer state when a raw element that is self-closing is encountered.
+
+  This fixes the handling of self-closing elements like `<title />` and `<script />` when used with `set:html`.
+
 ## 0.11.3
 
 ### Patch Changes

package/README.md

@@ -12,7 +12,15 @@ npm install @astrojs/compiler
 
 ## Usage
 
-_Note: API will change before 1.0! Use at your own discretion._
+_Note: Public APIs are likely to change before 1.0! Use at your own discretion._
+
+#### Transform `.astro` to valid TypeScript
+
+The Astro compiler can convert `.astro` syntax to a TypeScript Module whose default export generates HTML.
+
+**Some notes**...
+- TypeScript is valid `.astro` syntax! The output code may need an additional post-processing step to generate valid JavaScript.
+- `.astro` files rely on a server implementation exposed as `astro/internal` in the Node ecosystem. Other runtimes currently need to bring their own rendering implementation and reference it via `internalURL`. This is a pain point we're looking into fixing.
 
 ```js
 import { transform } from '@astrojs/compiler';
@@ -25,6 +33,31 @@ const result = await transform(source, {
 });
 ```
 
+#### Parse `.astro` and return an AST
+
+The Astro compiler can emit an AST using the `parse` method.
+
+**Some notes**...
+- Position data is currently incomplete and in some cases incorrect. We're working on it!
+- A `TextNode` can represent both HTML `text` and JavaScript/TypeScript source code.
+- The `@astrojs/compiler/utils` entrypoint exposes a `walk` function that can be used to traverse the AST. It also exposes the `is` helper which can be used as guards to derive the proper types for each `node`.
+
+```js
+import { parse } from '@astrojs/compiler';
+import { walk, is } from '@astrojs/compiler/utils';
+
+const result = await parse(source, {
+  position: false, // defaults to `true`
+});
+
+walk(result.ast, (node) => {
+  // `tag` nodes are `element` | `custom-element` | `component`
+  if (is.tag(node)) {
+    console.log(node.name);
+  }
+})
+```
+
 ## Contributing
 
 [CONTRIBUTING.md](./CONTRIBUTING.md)

package/browser/index.d.ts

@@ -1,3 +1,4 @@
 import type * as types from '../shared/types';
 export declare const transform: typeof types.transform;
+export declare const parse: typeof types.parse;
 export declare const initialize: typeof types.initialize;

package/browser/index.js

@@ -2,6 +2,9 @@ import Go from './wasm_exec.js';
 export const transform = (input, options) => {
     return ensureServiceIsRunning().transform(input, options);
 };
+export const parse = (input, options) => {
+    return ensureServiceIsRunning().parse(input, options);
+};
 let initializePromise;
 let longLivedService;
 export const initialize = async (options) => {
@@ -47,5 +50,6 @@ const startRunningService = async (wasmURL) => {
     const service = globalThis['@astrojs/compiler'];
     return {
         transform: (input, options) => new Promise((resolve) => resolve(service.transform(input, options || {}))),
+        parse: (input, options) => new Promise((resolve) => resolve(service.parse(input, options || {}))).then((result) => ({ ...result, ast: JSON.parse(result.ast) })),
     };
 };

package/browser/utils.d.ts

@@ -0,0 +1,20 @@
+import { Node, ParentNode, RootNode, ElementNode, CustomElementNode, ComponentNode, LiteralNode, ExpressionNode, TextNode, CommentNode, DoctypeNode, FrontmatterNode } from '../shared/ast';
+export interface Visitor {
+    (node: Node, parent?: ParentNode, index?: number): void | Promise<void>;
+}
+export declare const is: {
+    parent(node: Node): node is ParentNode;
+    literal(node: Node): node is LiteralNode;
+    tag(node: Node): node is ElementNode | ComponentNode | CustomElementNode;
+    whitespace(node: Node): node is TextNode;
+    root: (node: Node) => node is RootNode;
+    element: (node: Node) => node is ElementNode;
+    customElement: (node: Node) => node is CustomElementNode;
+    component: (node: Node) => node is ComponentNode;
+    expression: (node: Node) => node is ExpressionNode;
+    text: (node: Node) => node is TextNode;
+    doctype: (node: Node) => node is DoctypeNode;
+    comment: (node: Node) => node is CommentNode;
+    frontmatter: (node: Node) => node is FrontmatterNode;
+};
+export declare function walk(node: ParentNode, callback: Visitor): void;

package/browser/utils.js

@@ -0,0 +1,46 @@
+function guard(type) {
+    return (node) => node.type === type;
+}
+export const is = {
+    parent(node) {
+        return Array.isArray(node.children);
+    },
+    literal(node) {
+        return typeof node.value === 'string';
+    },
+    tag(node) {
+        return node.type === 'element' || node.type === 'custom-element' || node.type === 'component';
+    },
+    whitespace(node) {
+        return node.type === 'text' && node.value.trim().length === 0;
+    },
+    root: guard('root'),
+    element: guard('element'),
+    customElement: guard('custom-element'),
+    component: guard('component'),
+    expression: guard('expression'),
+    text: guard('text'),
+    doctype: guard('doctype'),
+    comment: guard('comment'),
+    frontmatter: guard('frontmatter'),
+};
+class Walker {
+    constructor(callback) {
+        this.callback = callback;
+    }
+    async visit(node, parent, index) {
+        await this.callback(node, parent, index);
+        if (is.parent(node)) {
+            let promises = [];
+            for (let i = 0; i < node.children.length; i++) {
+                const child = node.children[i];
+                promises.push(this.callback(child, node, i));
+            }
+            await Promise.all(promises);
+        }
+    }
+}
+export function walk(node, callback) {
+    const walker = new Walker(callback);
+    walker.visit(node);
+}

package/node/index.d.ts

@@ -1,3 +1,4 @@
 import type * as types from '../shared/types';
 export declare const transform: typeof types.transform;
+export declare const parse: typeof types.parse;
 export declare const compile: (template: string) => Promise<string>;

package/node/index.js

@@ -4,6 +4,9 @@ import { fileURLToPath } from 'url';
 export const transform = async (input, options) => {
     return getService().then((service) => service.transform(input, options));
 };
+export const parse = async (input, options) => {
+    return getService().then((service) => service.parse(input, options));
+};
 export const compile = async (template) => {
     const { default: mod } = await import(`data:text/javascript;charset=utf-8;base64,${Buffer.from(template).toString('base64')}`);
     return mod;
@@ -36,5 +39,6 @@ const startRunningService = async () => {
     const _service = globalThis['@astrojs/compiler'];
     return {
         transform: (input, options) => new Promise((resolve) => resolve(_service.transform(input, options || {}))),
+        parse: (input, options) => new Promise((resolve) => resolve(_service.parse(input, options || {}))).then((result) => ({ ...result, ast: JSON.parse(result.ast) })),
     };
 };

package/node/utils.d.ts

@@ -0,0 +1,20 @@
+import { Node, ParentNode, RootNode, ElementNode, CustomElementNode, ComponentNode, LiteralNode, ExpressionNode, TextNode, CommentNode, DoctypeNode, FrontmatterNode } from '../shared/ast';
+export interface Visitor {
+    (node: Node, parent?: ParentNode, index?: number): void | Promise<void>;
+}
+export declare const is: {
+    parent(node: Node): node is ParentNode;
+    literal(node: Node): node is LiteralNode;
+    tag(node: Node): node is ElementNode | ComponentNode | CustomElementNode;
+    whitespace(node: Node): node is TextNode;
+    root: (node: Node) => node is RootNode;
+    element: (node: Node) => node is ElementNode;
+    customElement: (node: Node) => node is CustomElementNode;
+    component: (node: Node) => node is ComponentNode;
+    expression: (node: Node) => node is ExpressionNode;
+    text: (node: Node) => node is TextNode;
+    doctype: (node: Node) => node is DoctypeNode;
+    comment: (node: Node) => node is CommentNode;
+    frontmatter: (node: Node) => node is FrontmatterNode;
+};
+export declare function walk(node: ParentNode, callback: Visitor): void;

package/node/utils.js

@@ -0,0 +1,46 @@
+function guard(type) {
+    return (node) => node.type === type;
+}
+export const is = {
+    parent(node) {
+        return Array.isArray(node.children);
+    },
+    literal(node) {
+        return typeof node.value === 'string';
+    },
+    tag(node) {
+        return node.type === 'element' || node.type === 'custom-element' || node.type === 'component';
+    },
+    whitespace(node) {
+        return node.type === 'text' && node.value.trim().length === 0;
+    },
+    root: guard('root'),
+    element: guard('element'),
+    customElement: guard('custom-element'),
+    component: guard('component'),
+    expression: guard('expression'),
+    text: guard('text'),
+    doctype: guard('doctype'),
+    comment: guard('comment'),
+    frontmatter: guard('frontmatter'),
+};
+class Walker {
+    constructor(callback) {
+        this.callback = callback;
+    }
+    async visit(node, parent, index) {
+        await this.callback(node, parent, index);
+        if (is.parent(node)) {
+            let promises = [];
+            for (let i = 0; i < node.children.length; i++) {
+                const child = node.children[i];
+                promises.push(this.callback(child, node, i));
+            }
+            await Promise.all(promises);
+        }
+    }
+}
+export function walk(node, callback) {
+    const walker = new Walker(callback);
+    walker.visit(node);
+}

package/package.json

@@ -5,12 +5,12 @@
   "type": "module",
   "bugs": "https://github.com/withastro/compiler/issues",
   "homepage": "https://astro.build",
-  "version": "0.11.3",
+  "version": "0.12.0-next.1",
   "scripts": {
     "build": "tsc -p ."
   },
   "main": "./node/index.js",
-  "types": "./shared/types.d.ts",
+  "types": "./node",
   "repository": {
     "type": "git",
     "url": "https://github.com/withastro/compiler.git"
@@ -21,7 +21,13 @@
       "import": "./node/index.js",
       "default": "./browser/index.js"
     },
-    "./astro.wasm": "./astro.wasm"
+    "./utils": {
+      "browser": "./browser/utils.js",
+      "import": "./node/utils.js",
+      "default": "./browser/utils.js"
+    },
+    "./astro.wasm": "./astro.wasm",
+    "./types.d.ts": "./types.d.ts"
   },
   "dependencies": {
     "typescript": "^4.3.5"

package/shared/ast.d.ts

@@ -0,0 +1,71 @@
+export declare type ParentNode = RootNode | ElementNode | ComponentNode | CustomElementNode | ExpressionNode;
+export declare type Node = RootNode | ElementNode | ComponentNode | CustomElementNode | ExpressionNode | TextNode | FrontmatterNode | DoctypeNode | CommentNode;
+export interface Position {
+    start: Point;
+    end?: Point;
+}
+export interface Point {
+    /** 1-based line number */
+    line: number;
+    /** 1-based column number, per-line */
+    column: number;
+    /** 0-based byte offset */
+    offset: number;
+}
+export interface BaseNode {
+    type: string;
+    position?: Position;
+}
+export interface ParentLikeNode extends BaseNode {
+    type: 'element' | 'component' | 'custom-element' | 'expression' | 'root';
+    children: Node[];
+}
+export interface LiteralNode extends BaseNode {
+    type: 'text' | 'doctype' | 'comment' | 'frontmatter';
+    value: string;
+}
+export interface RootNode extends ParentLikeNode {
+    type: 'root';
+}
+export interface AttributeNode extends BaseNode {
+    type: 'attribute';
+    kind: 'quoted' | 'empty' | 'expression' | 'spread' | 'shorthand' | 'template-literal';
+    name: string;
+    value: string;
+}
+export interface DirectiveNode extends Omit<AttributeNode, 'type'> {
+    type: 'directive';
+}
+export interface TextNode extends LiteralNode {
+    type: 'text';
+}
+export interface ElementNode extends ParentLikeNode {
+    type: 'element';
+    name: string;
+    attributes: AttributeNode[];
+    directives: DirectiveNode[];
+}
+export interface ComponentNode extends ParentLikeNode {
+    type: 'component';
+    name: string;
+    attributes: AttributeNode[];
+    directives: DirectiveNode[];
+}
+export interface CustomElementNode extends ParentLikeNode {
+    type: 'custom-element';
+    name: string;
+    attributes: AttributeNode[];
+    directives: DirectiveNode[];
+}
+export interface DoctypeNode extends LiteralNode {
+    type: 'doctype';
+}
+export interface CommentNode extends LiteralNode {
+    type: 'comment';
+}
+export interface FrontmatterNode extends LiteralNode {
+    type: 'frontmatter';
+}
+export interface ExpressionNode extends ParentLikeNode {
+    type: 'expression';
+}

package/shared/ast.js

@@ -0,0 +1 @@
+export {};

package/shared/types.d.ts

@@ -1,13 +1,21 @@
+import { RootNode } from './ast';
+export * from './ast';
 export interface PreprocessorResult {
     code: string;
     map?: string;
 }
+export interface ParseOptions {
+    position?: boolean;
+}
 export interface TransformOptions {
     internalURL?: string;
     site?: string;
     sourcefile?: string;
     pathname?: string;
     sourcemap?: boolean | 'inline' | 'external' | 'both';
+    /**
+     * @deprecated "as" has been removed and no longer has any effect!
+     */
     as?: 'document' | 'fragment';
     projectRoot?: string;
     preprocessStyle?: (content: string, attrs: Record<string, string>) => Promise<PreprocessorResult>;
@@ -28,7 +36,11 @@ export interface TransformResult {
     code: string;
     map: string;
 }
+export interface ParseResult {
+    ast: RootNode;
+}
 export declare function transform(input: string, options?: TransformOptions): Promise<TransformResult>;
+export declare function parse(input: string, options?: ParseOptions): Promise<ParseResult>;
 export declare function initialize(options: InitializeOptions): Promise<void>;
 export interface InitializeOptions {
     wasmURL?: string;

package/shared/types.js

@@ -1 +1 @@
-export {};
+export * from './ast';

package/types.d.ts

@@ -0,0 +1 @@
+export * from './shared/ast'

package/utils.d.ts

@@ -0,0 +1 @@
+export * from './node/utils';