ripple 0.3.12 → 0.3.14

package/tests/utils/vite-plugin-hmr.test.js

@@ -28,7 +28,7 @@ describe('vite-plugin-ripple hotUpdate', () => {
 				},
 			},
 			{
-				file: '/workspace/src/non-component.ripple',
+				file: '/workspace/src/non-component.rsrx',
 				modules: [{ id: 'client:non-component', isSelfAccepting: false }],
 				server: {
 					environments: {
@@ -43,8 +43,8 @@ describe('vite-plugin-ripple hotUpdate', () => {
 			},
 		);
 
-		expect(transform_request).toHaveBeenCalledWith('/src/non-component.ripple');
-		expect(get_ssr_modules).toHaveBeenCalledWith('/workspace/src/non-component.ripple');
+		expect(transform_request).toHaveBeenCalledWith('/src/non-component.rsrx');
+		expect(get_ssr_modules).toHaveBeenCalledWith('/workspace/src/non-component.rsrx');
 		expect(invalidate_ssr_module).toHaveBeenCalledTimes(2);
 		expect(send_hot_update).toHaveBeenCalledWith({ type: 'full-reload' });
 		expect(result).toEqual([]);
@@ -74,7 +74,7 @@ describe('vite-plugin-ripple hotUpdate', () => {
 				},
 			},
 			{
-				file: '/workspace/src/component.ripple',
+				file: '/workspace/src/component.rsrx',
 				modules: [{ id: 'client:component', isSelfAccepting: true }],
 				server: {
 					environments: {
@@ -89,7 +89,7 @@ describe('vite-plugin-ripple hotUpdate', () => {
 			},
 		);
 
-		expect(transform_request).toHaveBeenCalledWith('/src/component.ripple');
+		expect(transform_request).toHaveBeenCalledWith('/src/component.rsrx');
 		expect(get_ssr_modules).not.toHaveBeenCalled();
 		expect(invalidate_ssr_module).not.toHaveBeenCalled();
 		expect(send_hot_update).not.toHaveBeenCalled();

package/tsconfig.json

@@ -26,8 +26,10 @@
     "./*.js",
     "./src/",
     "./tests/**/*.test.ripple",
+    "./tests/**/*.test.rsrx",
     "./tests/**/*.test.tsrx",
     "./tests/**/*.ripple",
+    "./tests/**/*.rsrx",
     "./tests/**/*.tsrx",
     "./tests/**/*.d.ts",
     "./tests/**/*.js"

package/types/index.d.ts

@@ -141,18 +141,21 @@ declare global {
 
 export function createRefKey(): symbol;
 
+export const UNINITIALIZED: unique symbol;
+export const DERIVED_UPDATED: unique symbol;
+export const SUSPENSE_PENDING: unique symbol;
+export const SUSPENSE_REJECTED: unique symbol;
+
 // Base Tracked interface - all tracked values have a '#v' property containing the actual value
 interface TrackedBase<V> {
 	'#v': V;
 	value: V;
 }
-
 // Augment Tracked to be callable when V is a Component
 // This allows <@Something /> to work in JSX when Something is Tracked<Component>
 interface TrackedCallable<V> {
 	(props: V extends Component<infer P> ? P : never): V extends Component ? void : never;
 }
-
 // Supports indexed access: track(0)[0] → value, track(0)[1] → Tracked<V>
 // And destructuring `const [one, two] = track(0);`
 export type Tracked<V> = [V, Tracked<V>] & TrackedBase<V> & TrackedCallable<V>;
@@ -188,6 +191,14 @@ export function track<V>(
 // Overload for non-function values
 export function track<V>(value?: V, get?: (v: V) => V, set?: (next: V, prev: V) => V): Tracked<V>;
 
+export function trackAsync<V>(
+	value: () => PromiseLike<V> | { promise: PromiseLike<V>; abortController: AbortController },
+): Tracked<V>;
+
+export function trackPending<V>(value: Tracked<V> | (() => any)): boolean;
+
+export function peek<V>(tracked: Tracked<V>): V;
+
 export interface AddEventOptions extends ExtendedEventOptions {
 	customName?: string;
 }
@@ -531,24 +542,3 @@ export function bindFiles<V extends FileList>(
 	tracked: Tracked<V | null | undefined> | GetFunction<V | null | undefined>,
 	setter?: SetFunction<V>,
 ): (node: HTMLInputElement) => void;
-
-type ServerBlock = {};
-
-export interface RippleNamespace {
-	array: RippleArrayCallable;
-	object: RippleObjectCallable;
-	context: ContextCallable;
-	date: RippleDateCallable;
-	effect: typeof effect;
-	map: RippleMapCallable;
-	mediaQuery: MediaQueryCallable;
-	set: RippleSetCallable;
-	url: RippleURLCallable;
-	urlSearchParams: RippleURLSearchParamsCallable;
-	untrack: typeof untrack;
-	track: typeof track;
-	style: Record<string, string>;
-	server: ServerBlock;
-}
-
-export declare const ripple_namespace: RippleNamespace;

package/types/server.d.ts

@@ -1,5 +1,4 @@
-import type { Props } from '#public';
-import type { Readable } from 'node:stream';
+import type { Component } from '#public';
 
 // Re-export runtime types for server-compiled components
 export {
@@ -17,28 +16,56 @@ export {
 	RippleURLSearchParams,
 } from './index.js';
 
-export interface SSRRenderOutput {
+export interface RenderResult {
 	head: string;
 	body: string;
 	css: Set<string>;
+	topLevelError?: Error | null;
+}
+
+export interface RenderStreamResult {
+	stream: StreamSink;
+	topLevelError?: Error | null;
+}
+
+export interface StreamSink {
 	push(chunk: string): void;
-	register_css(hash: string): void;
+	close(): void;
+	error(reason: unknown): void;
 }
 
-export interface SSRComponent {
-	(output: SSRRenderOutput, props?: Props): void | Promise<void>;
-	async?: boolean;
+export type WebStream = ReadableStream<Uint8Array>;
+
+export interface Stream {
+	controller: ReadableStreamDefaultController<Uint8Array>;
+	textEncoder: TextEncoder;
+	stream: WebStream;
+	sink: StreamSink;
 }
 
-export interface SSRRenderResult {
-	head: string;
-	body: string;
-	css: Set<string>;
+export interface BaseRenderOptions {
+	stream?: StreamSink;
+	// defaults to true
+	// set to false to add more content
+	closeStream?: boolean;
+}
+
+export interface StreamingRenderOptions extends BaseRenderOptions {
+	stream: StreamSink;
 }
 
-export type SSRRender = (component: SSRComponent) => Promise<SSRRenderResult>;
-export type render = (component: SSRComponent) => Promise<SSRRenderResult>;
-export type renderToStream = (component: SSRComponent) => Readable;
+export interface RenderOptions extends BaseRenderOptions {
+	stream?: undefined;
+}
+
+export declare function create_ssr_stream(): Stream;
+
+export declare function render(
+	component: Component,
+	options?: RenderOptions,
+): Promise<RenderResult>;
 
-export const render: render;
-export const renderToStream: renderToStream;
+export declare function render(
+	component: Component,
+	options: StreamingRenderOptions,
+): Promise<RenderStreamResult>;

package/src/compiler/comment-utils.js

@@ -1,91 +0,0 @@
-/**
- * @import * as AST from 'estree'
- */
-
-/**
- * Check if a comment is a TypeScript pragma (line comment)
- * @param {AST.CommentWithLocation} comment
- * @returns {boolean}
- */
-export function is_ts_pragma(comment) {
-	if (comment.type !== 'Line') return false;
-
-	const pragmas = ['@ts-ignore', '@ts-expect-error', '@ts-nocheck', '@ts-check'];
-	return pragmas.some((pragma) => comment.value.trimStart().startsWith(pragma));
-}
-
-/**
- * Check if a comment is a triple-slash directive
- * /// <reference path="..." />
- * @param {AST.CommentWithLocation} comment
- * @returns {boolean}
- */
-export function is_triple_slash_directive(comment) {
-	if (comment.type !== 'Line') return false;
-
-	// Triple slash directives start with / after the // is stripped
-	// So the value should start with / followed by <reference, <amd-module, or <amd-dependency
-	const value = comment.value.trim();
-	return /^\/\s*<(reference|amd-module|amd-dependency)/.test(value);
-}
-
-/**
- * Check if a comment is a JSDoc comment with TypeScript annotations
- * Examples: block comments containing `@type`, `@typedef`, `@param`, `@returns`, etc.
- * @param {AST.CommentWithLocation} comment
- * @returns {boolean}
- */
-export function is_jsdoc_ts_annotation(comment) {
-	if (comment.type !== 'Block') return false;
-
-	// JSDoc comments start with /** which means the value starts with * after /* is stripped
-	if (!comment.value.startsWith('*')) return false;
-
-	// Check if it contains TypeScript-relevant tags
-	const tsAnnotations = [
-		'@type',
-		'@typedef',
-		'@param',
-		'@returns',
-		'@template',
-		'@extends',
-		'@implements',
-		'@satisfies',
-		'@overload',
-		'@import',
-	];
-
-	return tsAnnotations.some((annotation) => comment.value.includes(annotation));
-}
-
-/**
- * Check if a comment should be preserved in to_ts mode
- * @param {AST.CommentWithLocation} comment
- * @returns {boolean}
- */
-export function should_preserve_comment(comment) {
-	return (
-		is_ts_pragma(comment) || is_triple_slash_directive(comment) || is_jsdoc_ts_annotation(comment)
-	);
-}
-
-/**
- * Format a comment for output
- * @param {AST.CommentWithLocation} comment
- * @returns {string}
- */
-export function format_comment(comment) {
-	if (comment.type === 'Line') {
-		// Check if it's a triple-slash directive (value starts with /)
-		if (comment.value.trimStart().startsWith('/')) {
-			return `/// ${comment.value.trimStart().slice(1)}`;
-		}
-		return `// ${comment.value.trim()}`;
-	} else {
-		// Block comment - check if it's a JSDoc (value starts with *)
-		if (comment.value.startsWith('*')) {
-			return `/** ${comment.value.trim().slice(1)} */`;
-		}
-		return `/* ${comment.value.trim()} */`;
-	}
-}

package/src/compiler/errors.js

@@ -1,77 +0,0 @@
-/**
-@import * as AST from 'estree';
-@import { RippleCompileError } from 'ripple/compiler';
-*/
-
-/**
- *
- * @param {string} message
- * @param {string | null} filename
- * @param {AST.Node | AST.NodeWithLocation} node
- * @param {RippleCompileError[]} [errors]
- * @param {AST.CommentWithLocation[]} [comments]
- * @returns {void}
- */
-export function error(message, filename, node, errors, comments) {
-	if (errors && comments && is_ripple_error_suppressed(node, comments)) {
-		return;
-	}
-
-	const error = /** @type {RippleCompileError} */ (new Error(message));
-
-	// same as the acorn compiler error
-	error.pos = node.start ?? undefined;
-	error.raisedAt = node.end ?? undefined;
-
-	// custom properties
-	error.fileName = filename;
-	error.end = node.end ?? undefined;
-	error.loc = !node.loc
-		? undefined
-		: {
-				start: {
-					line: node.loc.start.line,
-					column: node.loc.start.column,
-				},
-				end: {
-					line: node.loc.end.line,
-					column: node.loc.end.column,
-				},
-			};
-
-	if (errors) {
-		error.type = 'usage';
-		errors.push(error);
-		return;
-	}
-
-	error.type = 'fatal';
-	throw error;
-}
-
-/**
- * @param {AST.CommentWithLocation} comment
- * @return {boolean}
- */
-function is_ripple_error_suppress_comment(comment) {
-	const text = comment.value.trim();
-	return text.startsWith('@ripple-ignore') || text.startsWith('@ripple-expect-error');
-}
-
-/**
- * @param {AST.Node | AST.NodeWithLocation} node
- * @param {AST.CommentWithLocation[]} comments
- */
-function is_ripple_error_suppressed(node, comments) {
-	if (node.loc) {
-		const node_start_line = node.loc.start.line;
-		for (const comment of comments) {
-			if (comment.type === 'Line' && comment.loc.start.line === node_start_line - 1) {
-				if (is_ripple_error_suppress_comment(comment)) {
-					return true;
-				}
-			}
-		}
-	}
-	return false;
-}

package/src/compiler/identifier-utils.js

@@ -1,80 +0,0 @@
-export const IDENTIFIER_OBFUSCATION_PREFIX = '_$_';
-export const STYLE_IDENTIFIER = IDENTIFIER_OBFUSCATION_PREFIX + encode_utf16_char('#') + 'style';
-export const SERVER_IDENTIFIER = IDENTIFIER_OBFUSCATION_PREFIX + encode_utf16_char('#') + 'server';
-export const CSS_HASH_IDENTIFIER = IDENTIFIER_OBFUSCATION_PREFIX + 'hash';
-
-const DECODE_UTF16_REGEX = /_u([0-9a-fA-F]{4})_/g;
-
-/**
- * @param {string} char
- * @returns {string}
- */
-function encode_utf16_char(char) {
-	return `_u${('0000' + char.charCodeAt(0).toString(16)).slice(-4)}_`;
-}
-
-/**
- * Finds the next uppercase character or returns name.length
- * @param {string} name
- * @param {number} start
- * @returns {number}
- */
-function find_next_uppercase(name, start) {
-	for (let i = start; i < name.length; i++) {
-		if (name[i] === name[i].toUpperCase()) {
-			return i;
-		}
-	}
-	return name.length;
-}
-
-/**
- * @param {string} encoded
- * @returns {string}
- */
-function decode_utf16_string(encoded) {
-	return encoded.replace(DECODE_UTF16_REGEX, (_, hex) => String.fromCharCode(parseInt(hex, 16)));
-}
-
-/**
- * @param {string} name
- * @returns {string}
- */
-export function obfuscate_identifier(name) {
-	const first_char = name[0];
-	let start = 0;
-	if (first_char === '@' || first_char === '#') {
-		const encoded = encode_utf16_char(first_char);
-		name = encoded + name.slice(1);
-		start = encoded.length;
-	} else if (first_char === first_char.toUpperCase()) {
-		start = 1;
-	}
-	const index = find_next_uppercase(name, start);
-
-	const first_part = name.slice(0, index);
-	const second_part = name.slice(index);
-
-	return (
-		IDENTIFIER_OBFUSCATION_PREFIX +
-		(second_part ? second_part + '__' + first_part : first_part + '__')
-	);
-}
-
-/**
- * @param {string} name
- * @returns {boolean}
- */
-export function is_identifier_obfuscated(name) {
-	return name.startsWith(IDENTIFIER_OBFUSCATION_PREFIX);
-}
-
-/**
- * @param {string} name
- * @returns {string}
- */
-export function deobfuscate_identifier(name) {
-	name = name.replaceAll(IDENTIFIER_OBFUSCATION_PREFIX, '');
-	const parts = name.split('__');
-	return decode_utf16_string((parts[1] ? parts[1] : '') + parts[0]);
-}

package/src/compiler/index.d.ts

@@ -1,127 +0,0 @@
-import type * as AST from 'estree';
-import type {
-	CodeInformation as VolarCodeInformation,
-	Mapping as VolarMapping,
-} from '@volar/language-core';
-import type { DocumentHighlightKind } from 'vscode-languageserver-types';
-import type { RawSourceMap } from 'source-map';
-
-// ============================================================================
-// Compiler API Exports
-// ============================================================================
-/**
- * Result of compilation operation
- */
-export interface CompileResult {
-	/** The transformed AST */
-	ast: AST.Program;
-	/** The generated JavaScript code with source map */
-	js: {
-		code: string;
-		map: RawSourceMap;
-	};
-	/** The generated CSS */
-	css: string;
-}
-
-export interface DefinitionLocation {
-	embeddedId: string; // e.g., 'style_0', 'style_1'
-	start: number; // start offset
-	end: number; // end offset
-}
-
-export interface PluginActionOverrides {
-	/** Whether to enable word document highlighting for this mapping */
-	wordHighlight?: {
-		kind: DocumentHighlightKind;
-	};
-	/** TypeScript diagnostic codes to suppress for this mapping */
-	suppressedDiagnostics?: number[];
-	/** Custom hover documentation for this mapping, false to disable */
-	hover?: string | false | ((content: string) => string);
-	/** Custom definition info for this mapping, false to disable */
-	definition?:
-		| {
-				description?: string; // just for reference
-				// Generic location for embedded content (CSS, etc.)
-				location?: DefinitionLocation;
-				// Replace the type name in hover/definition with a different name
-				// And provide the path to import the type definitions from
-				// the `ripple` package directory, e.g. `types/index.d.ts`
-				// Currently only supported by the definition plugin
-				typeReplace?: {
-					name: string;
-					path: string;
-				};
-		  }
-		| false;
-}
-
-export interface CustomMappingData extends PluginActionOverrides {
-	embeddedId?: string; // e.g. css regions: 'style_0', 'style_1', etc.
-	content?: string; // (e.g., css code)
-}
-
-export interface MappingData extends VolarCodeInformation {
-	customData: CustomMappingData;
-}
-
-export interface CodeMapping extends Omit<VolarMapping<MappingData>, 'generatedLengths'> {
-	generatedLengths: number[];
-	data: MappingData;
-}
-
-export interface VolarMappingsResult {
-	code: string;
-	mappings: CodeMapping[];
-	cssMappings: CodeMapping[];
-	errors: RippleCompileError[];
-}
-
-export interface RippleCompileError extends Error {
-	pos: number | undefined;
-	raisedAt: number | undefined;
-	end: number | undefined;
-	loc: AST.SourceLocation | undefined;
-	fileName: string | null;
-	type: 'fatal' | 'usage';
-}
-
-/**
- * Compilation options
- */
-
-interface SharedCompileOptions {
-	minify_css?: boolean;
-	dev?: boolean;
-}
-export interface CompileOptions extends SharedCompileOptions {
-	mode?: 'client' | 'server';
-	hmr?: boolean;
-	compat_kinds?: string[];
-}
-
-export interface ParseOptions {
-	loose?: boolean;
-	errors?: RippleCompileError[];
-	comments?: AST.CommentWithLocation[];
-}
-
-export interface AnalyzeOptions
-	extends ParseOptions, Pick<CompileOptions, 'mode' | 'compat_kinds'> {
-	errors?: RippleCompileError[];
-	to_ts?: boolean;
-}
-
-export interface VolarCompileOptions
-	extends Omit<ParseOptions, 'errors' | 'comments'>, SharedCompileOptions {}
-
-export function parse(source: string, options?: ParseOptions): AST.Program;
-
-export function compile(source: string, filename: string, options?: CompileOptions): CompileResult;
-
-export function compile_to_volar_mappings(
-	source: string,
-	filename: string,
-	options?: VolarCompileOptions,
-): VolarMappingsResult;

package/src/compiler/index.js

@@ -1,89 +0,0 @@
-/** @import * as AST from 'estree' */
-
-import { parse as parse_module } from './phases/1-parse/index.js';
-import { analyze } from './phases/2-analyze/index.js';
-import { transform_client } from './phases/3-transform/client/index.js';
-import { transform_server } from './phases/3-transform/server/index.js';
-import { convert_source_map_to_mappings } from './phases/3-transform/segments.js';
-
-/**
- * Parse Ripple source code to ESTree AST
- * @param {string} source
- * @returns {AST.Program}
- */
-export function parse(source) {
-	return parse_module(source, undefined, undefined);
-}
-
-/**
- * Compile Ripple source code to JS/CSS output
- * @param {string} source
- * @param {string} filename
- * @param {CompileOptions} [options]
- * @returns {object}
- */
-export function compile(source, filename, options = {}) {
-	const ast = parse_module(source, filename, undefined);
-	const analysis = analyze(ast, filename, options);
-	const result =
-		options.mode === 'server'
-			? transform_server(
-					filename,
-					source,
-					analysis,
-					options?.minify_css ?? false,
-					options?.dev ?? false,
-				)
-			: transform_client(
-					filename,
-					source,
-					analysis,
-					false,
-					options?.minify_css ?? false,
-					options?.hmr ?? false,
-				);
-
-	return result;
-}
-
-/** @import { PostProcessingChanges, LineOffsets } from './phases/3-transform/client/index.js' */
-/** @import { VolarMappingsResult, VolarCompileOptions, CompileOptions, RippleCompileError } from 'ripple/compiler' */
-
-/**
- * Compile Ripple component to Volar virtual code with TypeScript mappings
- * @param {string} source
- * @param {string} filename
- * @param {VolarCompileOptions} [options] - Compiler options
- * @returns {VolarMappingsResult} Volar mappings object
- */
-export function compile_to_volar_mappings(source, filename, options = {}) {
-	const errors = /** @type {RippleCompileError[]} */ ([]);
-	const comments = /** @type {AST.CommentWithLocation[]} */ ([]);
-	const ast = parse_module(source, filename, { ...options, errors, comments });
-	const analysis = analyze(ast, filename, {
-		to_ts: true,
-		loose: !!options?.loose,
-		errors,
-		comments,
-	});
-	const transformed = transform_client(
-		filename,
-		source,
-		analysis,
-		true,
-		options?.minify_css ?? false,
-	);
-
-	return {
-		...convert_source_map_to_mappings(
-			transformed.ast,
-			ast,
-			source,
-			transformed.js.code,
-			transformed.js.map,
-			/** @type {PostProcessingChanges} */ (transformed.js.post_processing_changes),
-			/** @type {LineOffsets} */ (transformed.js.line_offsets),
-		),
-		errors: transformed.errors,
-	};
-}