@stacksjs/stx
Version:
A performant UI Framework. Powered by Bun.
109 lines • 4.18 kB
TypeScript
import { LRUCache } from './performance-utils';
import type { StxOptions } from './types';
/**
* Clear the @once store - useful for testing and resetting state
*
* IMPORTANT: In server environments, call this at the start of each request
* to prevent @once content from being incorrectly skipped across requests.
*
* Alternatively, use request-scoped tracking by setting `context.__onceStore = new Set()`
* before processing templates. The processor will use context.__onceStore if available.
*
* @example
* ```typescript
* // Option 1: Clear global store per request
* app.use((req, res, next) => {
* clearOnceStore()
* next()
* })
*
* // Option 2: Use request-scoped store (preferred)
* const context = {
* __onceStore: new Set<string>(),
* ...otherData
* }
* await processDirectives(template, context, filePath, options)
* ```
*/
export declare function clearOnceStore(): void;
/**
* Process @include, @partial, @includeIf, @includeWhen, @includeUnless,
* @includeFirst, and @once directives.
*
* This is the main function for include processing. It handles all include
* variants and the @once directive for deduplication.
*
* @param template - The template string to process
* @param context - Template context with variables
* @param filePath - Path to the current template file
* @param options - STX processing options
* @param dependencies - Set to track included file dependencies (for caching)
* @returns The processed template with includes resolved
*
* @example
* ```typescript
* const deps = new Set<string>()
* const result = await processIncludes(
* '@include("header") <main>Content</main> @include("footer")',
* { title: 'My Page' },
* '/app/views/home.stx',
* options,
* deps
* )
* // deps now contains paths to header.stx and footer.stx
* ```
*/
export declare function processIncludes(template: string, context: Record<string, any>, filePath: string, options: StxOptions, dependencies: Set<string>, includeStack?: Set<string>): Promise<string>;
/**
* Process @push and @prepend directives to collect content into named stacks.
*
* This function extracts stack content and removes the directives from output.
* The collected content is stored in the `stacks` object for later rendering.
*
* @param template - The template string to process
* @param stacks - Object to collect stack content (mutated)
* @returns Template with @push/@prepend directives removed
*
* @example
* ```typescript
* const stacks: Record<string, string[]> = {}
* const result = processStackPushDirectives(`
* @push('scripts')
* <script src="app.js"></script>
* @endpush
* <div>Content</div>
* `, stacks)
* // result = '\n <div>Content</div>\n'
* // stacks = { scripts: ['<script src="app.js"></script>'] }
* ```
*/
export declare function processStackPushDirectives(template: string, stacks: Record<string, string[]>): string;
/**
* Process @stack directives by replacing them with collected stack content.
*
* This should be called AFTER `processStackPushDirectives` has collected
* all @push and @prepend content.
*
* @param template - The template string with @stack directives
* @param stacks - Object containing collected stack content
* @returns Template with @stack directives replaced by their content
*
* @example
* ```typescript
* const stacks = {
* scripts: ['<script src="a.js"></script>', '<script src="b.js"></script>'],
* styles: ['<link rel="stylesheet" href="app.css">']
* }
* const result = processStackReplacements(`
* <head>@stack('styles')</head>
* <body>...@stack('scripts')</body>
* `, stacks)
* ```
*/
export declare function processStackReplacements(template: string, stacks: Record<string, string[]>): string;
// Cache for partials to avoid repeated file reads (LRU with max 500 entries)
export declare const partialsCache: LRUCache<string, string>;
// Global store to track what has been included via @once
// WARNING: This persists across requests in long-running servers!
// Use clearOnceStore() at the start of each request, or use request-scoped tracking via context.__onceStore
export declare const onceStore: Set<string>;