@astrojs/compiler 0.11.1 → 0.12.0-next.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @astrojs/compiler
 
+## 0.11.3
+
+### Patch Changes
+
+- dcf15bf: Fixes bug causing a crash when using Astro.resolve on a hoisted script
+
+## 0.11.2
+
+### Patch Changes
+
+- 41cc6ef: Fix memory issue caused by duplicate WASM instantiations
+
 ## 0.11.1
 
 ### Patch Changes
@@ -31,6 +43,14 @@
 - 5fa9e53: Fix handling of special characters inside of expressions
 - 8aaa956: Formalize support for magic `data-astro-raw` attribute with new, official `is:raw` directive
 - c698350: Improve MathML support. `{}` inside of `<math>` is now treated as raw text rather than an expression construct.
+## 0.11.0-next.0
+
+### Minor Changes
+
+- 083d604: Do not render implicit tags created during the parsing process
+- d188c74: Remove "as" option, treats all documents as fragments that generate no implicit tags
+- c4b6b05: Add `parse` function which generates an AST
+- d84c3a2: 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)).
 
 ## 0.10.1
 

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,28 +2,32 @@ 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 = (options) => {
+export const initialize = async (options) => {
     let wasmURL = options.wasmURL;
     if (!wasmURL)
         throw new Error('Must provide the "wasmURL" option');
     wasmURL += '';
-    if (initializePromise)
-        throw new Error('Cannot call "initialize" more than once');
-    initializePromise = startRunningService(wasmURL);
-    initializePromise.catch(() => {
-        // Let the caller try again if this fails
-        initializePromise = void 0;
-    });
-    return initializePromise;
+    if (!initializePromise) {
+        initializePromise = startRunningService(wasmURL).catch((err) => {
+            // Let the caller try again if this fails.
+            initializePromise = void 0;
+            // But still, throw the error back up the caller.
+            throw err;
+        });
+    }
+    longLivedService = longLivedService || (await initializePromise);
 };
 let ensureServiceIsRunning = () => {
-    if (longLivedService)
-        return longLivedService;
-    if (initializePromise)
+    if (!initializePromise)
+        throw new Error('You need to call "initialize" before calling this');
+    if (!longLivedService)
         throw new Error('You need to wait for the promise returned from "initialize" to be resolved before calling this');
-    throw new Error('You need to call "initialize" before calling this');
+    return longLivedService;
 };
 const instantiateWASM = async (wasmURL, importObject) => {
     let response = undefined;
@@ -44,7 +48,8 @@ const startRunningService = async (wasmURL) => {
     const wasm = await instantiateWASM(wasmURL, go.importObject);
     go.run(wasm.instance);
     const service = globalThis['@astrojs/compiler'];
-    longLivedService = {
+    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

@@ -2,17 +2,26 @@ import { promises as fs } from 'fs';
 import Go from './wasm_exec.js';
 import { fileURLToPath } from 'url';
 export const transform = async (input, options) => {
-    return ensureServiceIsRunning().then((service) => service.transform(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;
 };
 let longLivedService;
-let ensureServiceIsRunning = () => {
-    if (longLivedService)
-        return Promise.resolve(longLivedService);
-    return startRunningService();
+let getService = () => {
+    if (!longLivedService) {
+        longLivedService = startRunningService().catch((err) => {
+            // Let the caller try again if this fails.
+            longLivedService = void 0;
+            // But still, throw the error back up the caller.
+            throw err;
+        });
+    }
+    return longLivedService;
 };
 const instantiateWASM = async (wasmURL, importObject) => {
     let response = undefined;
@@ -27,9 +36,9 @@ const startRunningService = async () => {
     const go = new Go();
     const wasm = await instantiateWASM(fileURLToPath(new URL('../astro.wasm', import.meta.url)), go.importObject);
     go.run(wasm.instance);
-    const service = globalThis['@astrojs/compiler'];
-    longLivedService = {
-        transform: (input, options) => new Promise((resolve) => resolve(service.transform(input, options || {}))),
+    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) })),
     };
-    return longLivedService;
 };

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.1",
+  "version": "0.12.0-next.0",
   "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,6 +21,11 @@
       "import": "./node/index.js",
       "default": "./browser/index.js"
     },
+    "./utils": {
+      "browser": "./browser/utils.js",
+      "import": "./node/utils.js",
+      "default": "./browser/utils.js"
+    },
     "./astro.wasm": "./astro.wasm"
   },
   "dependencies": {

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/utils.d.ts

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