@vyriy/static 0.5.6 → 0.6.0

package/README.md

@@ -15,9 +15,9 @@ Serve a static directory:
 ```bash
 vyriy-static
 vyriy-static dist
-vyriy-static build
-vyriy-static public
+vyriy-static public --cache static
 vyriy-static --port 3000 dist
+vyriy-static dist --spa --fallback index.html --cache static
 ```
 
 When no directory is provided to the CLI, it tries `dist`, `build`, `public`, `out`, and then the current directory.
@@ -25,9 +25,16 @@ When no directory is provided to the CLI, it tries `dist`, `build`, `public`, `o
 CLI flags:
 
 - `--port <port>` or `-p <port>` sets the local server port.
+- `--cache <preset>` sets `none`, `default`, `static`, or `immutable`.
+- `--index <file>` sets the static directory index file.
+- `--not-found <file>` sets the static `404` response file.
+- `--spa` enables SPA fallback mode.
+- `--fallback <file>` sets the SPA fallback file.
 - `--help` or `-h` prints command help.
 - `--version` or `-v` prints the package version.
 
+CLI option priority is explicit CLI args, then `VYRIY_STATIC_*` env variables, then defaults. Outside production, CLI serving defaults to `cache: 'none'` when `--cache` is omitted.
+
 ## API
 
 Install as a project dependency:
@@ -36,29 +43,75 @@ Install as a project dependency:
 npm install @vyriy/static
 ```
 
-Use handlers and router helpers from code:
+Use direct handlers:
 
 ```ts
-import { staticServer, useSpa, useStatic, withSpa, withStatic } from '@vyriy/static';
-import { createRouter } from '@vyriy/router';
+import { useSpa, useStatic } from '@vyriy/static';
+
+export const assets = useStatic('./public', {
+  cache: 'immutable',
+  index: false,
+});
+
+export const site = useStatic('./dist', {
+  cache: 'static',
+  index: 'index.html',
+  notFound: '404.html',
+});
+
+export const app = useSpa('./dist', {
+  cache: 'static',
+  fallback: 'index.html',
+});
+```
 
-export const assets = useStatic();
-export const app = useSpa({ directory: 'dist', index: 'index.html' });
+Use router helpers:
+
+```ts
+import { createRouter } from '@vyriy/router';
+import { withStatic } from '@vyriy/static';
 
 export const router = withStatic(createRouter())
-  .get('/api', () => ({ body: JSON.stringify({ ok: true }) }))
-  .static('/dist', { directory: 'dist' })
-  .static('/', { directory: 'public' });
-export const spaRouter = withSpa(createRouter(), 'dist');
+  .get('/api/health', () => ({ body: JSON.stringify({ ok: true }) }))
+  .static('/assets', './dist/assets', { cache: 'immutable' })
+  .spa('/app', './dist', { cache: 'static' })
+  .fallbackSpa('./landing-dist', { cache: 'static' });
+```
+
+`static` and `spa` mounts strip the route prefix before resolving files:
+
+```txt
+/assets/logo.svg       -> ./dist/assets/logo.svg
+/app/assets/main.js    -> ./dist/assets/main.js
+```
+
+Global fallbacks are explicit:
+
+- `fallback(handler)` registers a custom unmatched-request handler.
+- `fallbackStatic(directory, options?)` serves unmatched requests through static file behavior.
+- `fallbackSpa(directory, options?)` serves unmatched requests through SPA fallback behavior.
+
+Only one fallback can be registered on a wrapped router.
+
+## Cache
+
+Cache presets:
+
+- `false` or `'none'` sends `Cache-Control: no-store`.
+- `'default'` sends `public, max-age=3600` with validators.
+- `'immutable'` sends `public, max-age=31536000, immutable` with validators.
+- `'static'` caches assets long-term and revalidates HTML and metadata.
+
+The `static` preset is designed for S3/CloudFront, Storybook, SPA builds, MFE assets, and static sites:
 
-const code = await staticServer({ directory: 'dist' });
+```txt
+assets -> long immutable cache
+html/json/xml/txt/yml -> no-cache + ETag + Last-Modified
+SPA fallback index.html -> no-cache + ETag + Last-Modified
 ```
 
-- `useStatic({ directory, index, error })` serves files from a directory.
-- `useSpa(options)` serves static files and falls back to the configured index file for missing `GET` and `HEAD` paths.
-- `withStatic(router).static(path, options)` adds prefix-based static mounts.
-- `withStatic(router, options).static(path)` keeps a shared default for static mounts.
-- `withSpa(router, directoryOrOptions)` adds static-first SPA fallback behavior.
+Defaults:
 
-Defaults are `directory: 'dist'`, `index: 'index.html'`, and `error: '404.html'`.
-When `staticServer()` is called without options, it tries `dist`, `build`, `public`, `out`, and then the current directory.
+- `useStatic('./dist')` uses `index: 'index.html'`, `notFound: false`, and `cache: 'default'`.
+- `useSpa('./dist')` uses `fallback: 'index.html'` and `cache: 'static'`.
+- `staticServer()` tries `dist`, `build`, `public`, `out`, and then the current directory.

package/cache.d.ts

@@ -0,0 +1,10 @@
+import type { ApiEvent, ApiResult } from '@vyriy/handler';
+import type { StaticCacheConfig, StaticCacheOptions, StaticCachePreset } from './types.js';
+type ResolvedCacheOptions = Required<Pick<StaticCacheOptions, 'etag' | 'lastModified'>> & Pick<StaticCacheOptions, 'immutable' | 'maxAge' | 'staleIfError' | 'staleWhileRevalidate'> & {
+    readonly cacheControl: string;
+};
+export declare const resolveCacheOptions: (cache: StaticCacheConfig | undefined, filePath: string, defaultCache: StaticCachePreset) => ResolvedCacheOptions;
+export declare const createEtag: (size: number, modifiedTime: Date) => string;
+export declare const createCacheHeaders: (cache: ResolvedCacheOptions, size: number, modifiedTime: Date) => Record<string, string>;
+export declare const maybeNotModified: (event: ApiEvent, headers: Record<string, string>) => ApiResult | undefined;
+export {};

package/cache.js

@@ -0,0 +1,166 @@
+import path from 'node:path';
+const ASSET_EXTENSIONS = new Set([
+    '.avif',
+    '.css',
+    '.gif',
+    '.ico',
+    '.jpeg',
+    '.jpg',
+    '.js',
+    '.map',
+    '.mjs',
+    '.png',
+    '.svg',
+    '.webp',
+    '.woff',
+    '.woff2',
+]);
+const extensionGroupPattern = /\.\{([^}]+)\}$/;
+const toCacheOptions = (cache) => {
+    if (cache === false || cache === 'none') {
+        return {
+            etag: false,
+            lastModified: false,
+        };
+    }
+    if (cache === 'immutable') {
+        return {
+            etag: true,
+            immutable: true,
+            lastModified: true,
+            maxAge: 31_536_000,
+        };
+    }
+    if (cache === 'default' || cache === 'static' || cache === undefined) {
+        return {
+            etag: true,
+            lastModified: true,
+            maxAge: 3_600,
+        };
+    }
+    return cache;
+};
+const matchRule = (filePath, match) => {
+    const extension = path.extname(filePath).toLowerCase();
+    const extensionGroup = extensionGroupPattern.exec(match);
+    if (extensionGroup) {
+        return extensionGroup[1].split(',').some((value) => extension === `.${value.trim().toLowerCase()}`);
+    }
+    if (match.startsWith('**/*.')) {
+        return extension === match.slice('**/*'.length).toLowerCase();
+    }
+    return filePath === match || filePath.endsWith(match);
+};
+const resolveStaticPreset = (extension) => {
+    if (ASSET_EXTENSIONS.has(extension)) {
+        return {
+            etag: true,
+            immutable: true,
+            lastModified: true,
+            maxAge: 31_536_000,
+        };
+    }
+    return {
+        etag: true,
+        lastModified: true,
+        maxAge: 0,
+    };
+};
+const resolveRule = (cache, filePath) => {
+    if (typeof cache !== 'object' || !('rules' in cache)) {
+        return cache;
+    }
+    const rule = cache.rules.find(({ match }) => {
+        const matches = typeof match === 'string'
+            ? [
+                match,
+            ]
+            : match;
+        return matches.some((item) => matchRule(filePath, item));
+    });
+    return rule?.cache ?? cache.fallback;
+};
+export const resolveCacheOptions = (cache, filePath, defaultCache) => {
+    const extension = path.extname(filePath).toLowerCase();
+    const selectedCache = cache === 'static' ? resolveStaticPreset(extension) : resolveRule(cache ?? defaultCache, filePath);
+    const options = toCacheOptions(selectedCache);
+    const noStore = selectedCache === false || selectedCache === 'none';
+    if (noStore) {
+        return {
+            cacheControl: 'no-store',
+            etag: false,
+            lastModified: false,
+        };
+    }
+    const maxAge = options.maxAge ?? 3_600;
+    const directives = maxAge === 0
+        ? [
+            'no-cache',
+        ]
+        : [
+            'public',
+            `max-age=${maxAge}`,
+        ];
+    if (options.immutable) {
+        directives.push('immutable');
+    }
+    if (options.staleWhileRevalidate !== undefined) {
+        directives.push(`stale-while-revalidate=${options.staleWhileRevalidate}`);
+    }
+    if (options.staleIfError !== undefined) {
+        directives.push(`stale-if-error=${options.staleIfError}`);
+    }
+    return {
+        cacheControl: directives.join(', '),
+        etag: options.etag ?? true,
+        immutable: options.immutable,
+        lastModified: options.lastModified ?? true,
+        maxAge,
+        staleIfError: options.staleIfError,
+        staleWhileRevalidate: options.staleWhileRevalidate,
+    };
+};
+export const createEtag = (size, modifiedTime) => `W/"${size.toString(16)}-${Math.trunc(modifiedTime.getTime()).toString(16)}"`;
+export const createCacheHeaders = (cache, size, modifiedTime) => {
+    const headers = {
+        'cache-control': cache.cacheControl,
+    };
+    if (cache.etag) {
+        headers.etag = createEtag(size, modifiedTime);
+    }
+    if (cache.lastModified) {
+        headers['last-modified'] = modifiedTime.toUTCString();
+    }
+    return headers;
+};
+export const maybeNotModified = (event, headers) => {
+    const requestHeaders = event.headers ?? {};
+    const ifNoneMatch = requestHeaders['if-none-match'] ?? requestHeaders['If-None-Match'];
+    if (ifNoneMatch) {
+        if (headers.etag &&
+            ifNoneMatch
+                .split(',')
+                .map((value) => value.trim())
+                .includes(headers.etag)) {
+            return {
+                body: '',
+                headers,
+                statusCode: 304,
+            };
+        }
+        return undefined;
+    }
+    const ifModifiedSince = requestHeaders['if-modified-since'] ?? requestHeaders['If-Modified-Since'];
+    if (ifModifiedSince && headers['last-modified']) {
+        const requestTime = Date.parse(ifModifiedSince);
+        const modifiedTime = Date.parse(headers['last-modified']);
+        if (!Number.isNaN(requestTime) && modifiedTime <= requestTime) {
+            return {
+                body: '',
+                headers,
+                statusCode: 304,
+            };
+        }
+    }
+    return undefined;
+};

package/content.d.ts

@@ -0,0 +1,2 @@
+export declare const getContentType: (extension: string) => string;
+export declare const isTextExtension: (extension: string) => boolean;

package/content.js

@@ -0,0 +1,40 @@
+const CONTENT_TYPES = {
+    '.avif': 'image/avif',
+    '.css': 'text/css; charset=utf-8',
+    '.csv': 'text/csv; charset=utf-8',
+    '.gif': 'image/gif',
+    '.html': 'text/html; charset=utf-8',
+    '.ico': 'image/x-icon',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.js': 'text/javascript; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.map': 'application/json; charset=utf-8',
+    '.mjs': 'text/javascript; charset=utf-8',
+    '.pdf': 'application/pdf',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml; charset=utf-8',
+    '.txt': 'text/plain; charset=utf-8',
+    '.webp': 'image/webp',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.xml': 'application/xml; charset=utf-8',
+    '.yaml': 'text/yaml; charset=utf-8',
+    '.yml': 'text/yaml; charset=utf-8',
+};
+const TEXT_TYPES = new Set([
+    '.css',
+    '.csv',
+    '.html',
+    '.js',
+    '.json',
+    '.map',
+    '.mjs',
+    '.svg',
+    '.txt',
+    '.xml',
+    '.yaml',
+    '.yml',
+]);
+export const getContentType = (extension) => CONTENT_TYPES[extension.toLowerCase()] ?? 'application/octet-stream';
+export const isTextExtension = (extension) => TEXT_TYPES.has(extension.toLowerCase());

package/file.d.ts

@@ -0,0 +1,7 @@
+export declare const isInsideDirectory: (directory: string, candidate: string) => boolean;
+export declare const resolveRoot: (directory: string) => Promise<string>;
+export declare const resolveExistingFile: (root: string, requestPath: string, index: false | string) => Promise<{
+    filePath: string;
+    modifiedTime: Date;
+    size: number;
+} | undefined>;

package/file.js

@@ -0,0 +1,42 @@
+import { realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+export const isInsideDirectory = (directory, candidate) => {
+    const relative = path.relative(directory, candidate);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+};
+export const resolveRoot = (directory) => realpath(directory);
+export const resolveExistingFile = async (root, requestPath, index) => {
+    const requestedPath = requestPath.replace(/^\/+/, '') || index || '';
+    let candidate = path.resolve(root, requestedPath);
+    if (!isInsideDirectory(root, candidate)) {
+        return undefined;
+    }
+    try {
+        const candidateStat = await stat(candidate);
+        if (candidateStat.isDirectory()) {
+            if (!index) {
+                return undefined;
+            }
+            candidate = path.join(candidate, index);
+        }
+    }
+    catch {
+        return undefined;
+    }
+    if (!isInsideDirectory(root, candidate)) {
+        return undefined;
+    }
+    const realFilePath = await realpath(candidate);
+    if (!isInsideDirectory(root, realFilePath)) {
+        return undefined;
+    }
+    const fileStat = await stat(realFilePath);
+    if (!fileStat.isFile()) {
+        return undefined;
+    }
+    return {
+        filePath: realFilePath,
+        modifiedTime: fileStat.mtime,
+        size: fileStat.size,
+    };
+};

package/index.d.ts

@@ -2,5 +2,4 @@ export * from './server.js';
 export * from './use-static.js';
 export * from './use-spa.js';
 export * from './with-static.js';
-export * from './with-spa.js';
 export type * from './types.js';

package/index.js

@@ -2,4 +2,3 @@ export * from './server.js';
 export * from './use-static.js';
 export * from './use-spa.js';
 export * from './with-static.js';
-export * from './with-spa.js';

package/options.d.ts

@@ -0,0 +1,14 @@
+import type { StaticCacheConfig, UseSpaOptions, UseStaticOptions } from './types.js';
+export type NormalizedStaticOptions = UseStaticOptions & {
+    readonly cache: StaticCacheConfig;
+    readonly directory: string;
+    readonly index: false | string;
+    readonly notFound: false | string;
+};
+export type NormalizedSpaOptions = UseSpaOptions & {
+    readonly cache: StaticCacheConfig;
+    readonly directory: string;
+    readonly fallback: string;
+};
+export declare const normalizeStaticOptions: (directory?: string, options?: UseStaticOptions) => NormalizedStaticOptions;
+export declare const normalizeSpaOptions: (directory?: string, options?: UseSpaOptions) => NormalizedSpaOptions;

package/options.js

@@ -0,0 +1,18 @@
+const DEFAULT_DIRECTORY = 'dist';
+const DEFAULT_FALLBACK = 'index.html';
+const DEFAULT_INDEX = 'index.html';
+export const normalizeStaticOptions = (directory = DEFAULT_DIRECTORY, options = {}) => {
+    return {
+        cache: options.cache ?? 'default',
+        directory,
+        headers: options.headers,
+        index: options.index ?? DEFAULT_INDEX,
+        notFound: options.notFound ?? false,
+    };
+};
+export const normalizeSpaOptions = (directory = DEFAULT_DIRECTORY, options = {}) => ({
+    cache: options.cache ?? 'static',
+    directory,
+    fallback: options.fallback ?? DEFAULT_FALLBACK,
+    headers: options.headers,
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vyriy/static",
-  "version": "0.5.6",
+  "version": "0.6.0",
   "description": "Static file and SPA serving helpers for Vyriy servers.",
   "type": "module",
   "bin": {
@@ -8,9 +8,9 @@
     "vyriy-static": "./bin/index.js"
   },
   "dependencies": {
-    "@vyriy/handler": "0.5.6",
-    "@vyriy/router": "0.5.6",
-    "@vyriy/server": "0.5.6"
+    "@vyriy/handler": "0.6.0",
+    "@vyriy/router": "0.6.0",
+    "@vyriy/server": "0.6.0"
   },
   "agents": "./AGENTS.md",
   "license": "MIT",
@@ -27,6 +27,36 @@
       "import": "./index.js",
       "default": "./index.js"
     },
+    "./cache": {
+      "types": "./cache.d.ts",
+      "import": "./cache.js",
+      "default": "./cache.js"
+    },
+    "./cache.js": {
+      "types": "./cache.d.ts",
+      "import": "./cache.js",
+      "default": "./cache.js"
+    },
+    "./content": {
+      "types": "./content.d.ts",
+      "import": "./content.js",
+      "default": "./content.js"
+    },
+    "./content.js": {
+      "types": "./content.d.ts",
+      "import": "./content.js",
+      "default": "./content.js"
+    },
+    "./file": {
+      "types": "./file.d.ts",
+      "import": "./file.js",
+      "default": "./file.js"
+    },
+    "./file.js": {
+      "types": "./file.d.ts",
+      "import": "./file.js",
+      "default": "./file.js"
+    },
     "./index": {
       "types": "./index.d.ts",
       "import": "./index.js",
@@ -37,6 +67,16 @@
       "import": "./index.js",
       "default": "./index.js"
     },
+    "./options": {
+      "types": "./options.d.ts",
+      "import": "./options.js",
+      "default": "./options.js"
+    },
+    "./options.js": {
+      "types": "./options.d.ts",
+      "import": "./options.js",
+      "default": "./options.js"
+    },
     "./server": {
       "types": "./server.d.ts",
       "import": "./server.js",
@@ -67,16 +107,6 @@
       "import": "./use-static.js",
       "default": "./use-static.js"
     },
-    "./with-spa": {
-      "types": "./with-spa.d.ts",
-      "import": "./with-spa.js",
-      "default": "./with-spa.js"
-    },
-    "./with-spa.js": {
-      "types": "./with-spa.d.ts",
-      "import": "./with-spa.js",
-      "default": "./with-spa.js"
-    },
     "./with-static": {
       "types": "./with-static.d.ts",
       "import": "./with-static.js",

package/server.d.ts

@@ -1,10 +1,15 @@
-import type { StaticServer } from './types.js';
+import type { StaticCachePreset, StaticServer } from './types.js';
 export type StaticBinCommand = {
     readonly type: 'help' | 'version';
 } | {
+    readonly cache?: StaticCachePreset;
     readonly type: 'serve';
     readonly directory?: string;
+    readonly fallback?: string;
+    readonly index?: false | string;
+    readonly notFound?: false | string;
     readonly port?: string;
+    readonly spa?: boolean;
 };
 export type RunStaticCli = (args?: readonly string[], command?: string, alias?: false | string) => Promise<void>;
 export declare const staticVersion: string;

package/server.js

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
 import { server } from '@vyriy/server';
 import packageJson from './package.json' with { type: 'json' };
+import { useSpa } from './use-spa.js';
 import { useStatic } from './use-static.js';
 const DIRECTORIES = [
     'dist',
@@ -16,32 +17,85 @@ const getOptionValue = (args, name, alias) => {
     const index = args.findIndex((arg) => arg === name || arg === alias);
     return index >= 0 ? args[index + 1] : undefined;
 };
+const hasOption = (args, name) => args.includes(name);
 const isOptionValue = (args, index) => {
     const previous = args[index - 1];
-    return previous === '--port' || previous === '-p';
+    return (previous === '--cache' ||
+        previous === '--fallback' ||
+        previous === '--index' ||
+        previous === '--not-found' ||
+        previous === '--port' ||
+        previous === '-p');
 };
 const resolveDirectory = (directory) => directory ?? DIRECTORIES.find((candidate) => existsSync(candidate)) ?? '.';
 const createStaticHandler = useStatic;
+const createSpaHandler = useSpa;
+const normalizeCachePreset = (value) => {
+    if (!value) {
+        return undefined;
+    }
+    if (value === 'false' || value === 'none') {
+        return 'none';
+    }
+    if (value === 'default' || value === 'immutable' || value === 'static') {
+        return value;
+    }
+    throw new Error(`Unsupported static cache preset: ${value}`);
+};
+const getCliCacheDefault = () => (process.env.NODE_ENV === 'production' ? 'default' : 'none');
+const withEnvDefaults = (command) => ({
+    cache: command.cache ?? normalizeCachePreset(process.env.VYRIY_STATIC_CACHE) ?? getCliCacheDefault(),
+    directory: command.directory,
+    fallback: command.fallback ?? process.env.VYRIY_STATIC_FALLBACK,
+    index: command.index ?? process.env.VYRIY_STATIC_INDEX,
+    notFound: command.notFound ?? process.env.VYRIY_STATIC_NOT_FOUND,
+    spa: command.spa,
+});
 export const staticVersion = packageJson.version;
 export const createStaticHelpText = (command = 'vyriy-static', alias = 'vs') => {
     const aliasText = alias ? `  ${alias} [directory]                  Alias for ${command}\n` : '';
-    const aliasExampleText = alias ? `\n  ${alias} .` : '';
+    const aliasExampleText = alias ? `\n  ${alias} .\n  ${alias} --spa` : '';
     return `Vyriy Static Server
 
 Usage:
   ${command} [directory]        Serve a static directory (defaults to dist when it exists)
+  ${command} [directory] --spa  Serve a static directory in SPA fallback mode
   ${command} --port 3000 dist   Serve a directory on a specific port
 ${aliasText}\
+  ${command} --spa              Serve as an SPA with index fallback
+  ${command} --cache static     Set cache preset: none, default, static, immutable
   ${command} --help, -h         Show help
   ${command} --version, -v      Show version
 
 Options:
-  -p, --port <port>             Port passed through the PORT environment variable
+  -p, --port <port>             HTTP port. Default: PORT env or 3000
+  --cache <preset>              Cache preset: none, default, static, immutable
+  --index <file>                Static directory index file. Default: index.html
+  --not-found <file>            Static 404 response file. Default: disabled
+  --spa                         Enable SPA fallback mode. Default: false
+  --fallback <file>             SPA fallback file. Default: index.html
+
+Defaults:
+  directory                     First existing: dist, build, public, out, then .
+  port                          PORT env or 3000
+  cache                         none when NODE_ENV is not production; default in production
+  index                         index.html
+  not-found                     disabled unless --not-found is provided
+  spa                           false
+  fallback                      index.html
+
+Cache presets:
+  none                          Cache-Control: no-store
+  default                       public, max-age=3600 with validators
+  static                        immutable assets, revalidated HTML and metadata
+  immutable                     public, max-age=31536000, immutable
 
 Examples:
   ${command}
   ${command} public
-  ${command} --port 3000 dist${aliasExampleText}`;
+  ${command} --port 3000 dist
+  ${command} dist --cache static
+  ${command} dist --spa --fallback index.html --cache static${aliasExampleText}`;
 };
 export const parseStaticBinArgs = (args) => {
     if (args.includes('--help') || args.includes('-h')) {
@@ -50,11 +104,33 @@ export const parseStaticBinArgs = (args) => {
     if (args.includes('--version') || args.includes('-v')) {
         return { type: 'version' };
     }
-    return {
+    const cache = normalizeCachePreset(getOptionValue(args, '--cache', '--cache'));
+    const directory = args.find((arg, index) => !arg.startsWith('-') && !isOptionValue(args, index));
+    const fallback = getOptionValue(args, '--fallback', '--fallback');
+    const index = getOptionValue(args, '--index', '--index');
+    const notFound = getOptionValue(args, '--not-found', '--not-found');
+    const port = getOptionValue(args, '--port', '-p');
+    const command = {
         type: 'serve',
-        directory: args.find((arg, index) => !arg.startsWith('-') && !isOptionValue(args, index)),
-        port: getOptionValue(args, '--port', '-p'),
+        directory,
+        port,
     };
+    if (cache !== undefined) {
+        command.cache = cache;
+    }
+    if (fallback !== undefined) {
+        command.fallback = fallback;
+    }
+    if (index !== undefined) {
+        command.index = index;
+    }
+    if (notFound !== undefined) {
+        command.notFound = notFound;
+    }
+    if (hasOption(args, '--spa')) {
+        command.spa = true;
+    }
+    return command;
 };
 export const runStaticCli = async (args = [], command = 'vyriy-static', alias = 'vs') => {
     const parsed = parseStaticBinArgs(args);
@@ -71,11 +147,17 @@ export const runStaticCli = async (args = [], command = 'vyriy-static', alias =
             if (parsed.port) {
                 process.env.PORT = parsed.port;
             }
-            process.exitCode = await staticServer({ directory: parsed.directory });
+            process.exitCode = await staticServer(withEnvDefaults(parsed));
             break;
     }
 };
 export const staticServer = async (options = {}) => {
-    await Promise.resolve(server(createStaticHandler({ ...options, directory: resolveDirectory(options.directory) })));
+    const handlerOptions = {
+        ...options,
+        directory: resolveDirectory(options.directory),
+    };
+    await Promise.resolve(server(options.spa
+        ? createSpaHandler(handlerOptions.directory, handlerOptions)
+        : createStaticHandler(handlerOptions.directory, handlerOptions)));
     return 0;
 };

package/types.d.ts

@@ -1,15 +1,51 @@
 import type { ApiEvent, ApiResult, Handler } from '@vyriy/handler';
-import type { RouterApi } from '@vyriy/router';
-export type StaticOptions = {
+import type { Handler as RouterHandler, RouterApi } from '@vyriy/router';
+export type StaticCachePreset = false | 'none' | 'default' | 'static' | 'immutable';
+export type StaticCacheOptions = {
+    readonly etag?: boolean;
+    readonly immutable?: boolean;
+    readonly lastModified?: boolean;
+    readonly maxAge?: number;
+    readonly staleIfError?: number;
+    readonly staleWhileRevalidate?: number;
+};
+export type StaticCacheRule = {
+    readonly cache: StaticCachePreset | StaticCacheOptions;
+    readonly match: string | readonly string[];
+};
+export type StaticCacheConfig = StaticCachePreset | StaticCacheOptions | {
+    readonly fallback?: StaticCachePreset | StaticCacheOptions;
+    readonly rules: readonly StaticCacheRule[];
+};
+export type StaticHeaderContext = {
+    readonly filePath: string;
+    readonly requestPath: string;
+    readonly statusCode: number;
+};
+export type StaticBaseOptions = {
+    readonly cache?: StaticCacheConfig;
+    readonly headers?: HeadersInit | ((context: StaticHeaderContext) => HeadersInit);
+};
+export type UseStaticOptions = StaticBaseOptions & {
+    readonly index?: false | string;
+    readonly notFound?: false | string;
+};
+export type UseSpaOptions = StaticBaseOptions & {
+    readonly fallback?: string;
+};
+export type StaticServerOptions = (UseStaticOptions | UseSpaOptions) & {
     readonly directory?: string;
-    readonly index?: string;
-    readonly error?: string;
+    readonly spa?: boolean;
 };
-export type StaticMountOptions = StaticOptions | string;
 export type StaticHandler = Handler<ApiEvent, ApiResult>;
-export type StaticServer = (options?: StaticOptions) => Promise<number>;
+export type StaticServer = (options?: StaticServerOptions) => Promise<number>;
 export type StaticRouterApi = Omit<RouterApi, 'delete' | 'fallback' | 'get' | 'patch' | 'post' | 'put'> & {
-    static(path: string, options?: StaticMountOptions): StaticRouterApi;
+    static(path: string, directory: string, options?: UseStaticOptions): StaticRouterApi;
+    spa(path: string, directory: string, options?: UseSpaOptions): StaticRouterApi;
+    fallbackStatic(directory: string, options?: UseStaticOptions): StaticRouterApi;
+    fallbackSpa(directory: string, options?: UseSpaOptions): StaticRouterApi;
+} & {
+    [Method in Extract<keyof RouterApi, 'delete' | 'get' | 'patch' | 'post' | 'put'>]: (...args: Parameters<RouterApi[Method]>) => StaticRouterApi;
 } & {
-    [Method in Extract<keyof RouterApi, 'delete' | 'fallback' | 'get' | 'patch' | 'post' | 'put'>]: (...args: Parameters<RouterApi[Method]>) => StaticRouterApi;
+    fallback(handler: RouterHandler): StaticRouterApi;
 };

package/use-spa.d.ts

@@ -1,2 +1,2 @@
-import type { StaticHandler, StaticOptions } from './types.js';
-export declare const useSpa: (options?: StaticOptions) => StaticHandler;
+import type { StaticHandler, UseSpaOptions } from './types.js';
+export declare const useSpa: (directory?: string, options?: UseSpaOptions) => StaticHandler;

package/use-spa.js

@@ -1,17 +1,101 @@
-import { useStatic } from './use-static.js';
-const createStaticHandler = useStatic;
-const isSpaFallbackMethod = (method) => method === 'GET' || method === 'HEAD';
-export const useSpa = (options = {}) => {
-    const handler = createStaticHandler(options);
-    const index = options.index ?? 'index.html';
-    return async (event, context) => {
-        const result = await handler(event, context);
-        if (result.statusCode !== 404 || !isSpaFallbackMethod(event.httpMethod)) {
-            return result;
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { createCacheHeaders, maybeNotModified, resolveCacheOptions } from './cache.js';
+import { getContentType, isTextExtension } from './content.js';
+import { resolveExistingFile, resolveRoot } from './file.js';
+import { normalizeSpaOptions } from './options.js';
+const NOT_FOUND_BODY = JSON.stringify({ message: 'Not Found' });
+const METHOD_NOT_ALLOWED_BODY = JSON.stringify({ message: 'Method Not Allowed' });
+const isSpaMethod = (method) => method === 'GET' || method === 'HEAD';
+const toHeadersObject = (headers) => {
+    if (!headers) {
+        return {};
+    }
+    if (headers instanceof Headers) {
+        return Object.fromEntries(headers.entries());
+    }
+    if (Array.isArray(headers)) {
+        return Object.fromEntries(headers);
+    }
+    return Object.fromEntries(Object.entries(headers).map(([key, value]) => [key, String(value)]));
+};
+const notFound = () => ({
+    statusCode: 404,
+    body: NOT_FOUND_BODY,
+    headers: {
+        'content-type': 'application/json; charset=utf-8',
+    },
+});
+const methodNotAllowed = () => ({
+    statusCode: 405,
+    body: METHOD_NOT_ALLOWED_BODY,
+    headers: {
+        allow: 'GET, HEAD',
+        'content-type': 'application/json; charset=utf-8',
+    },
+});
+const createFileResult = async (event, requestPath, file, options) => {
+    const extension = path.extname(file.filePath);
+    const isText = isTextExtension(extension);
+    const cache = resolveCacheOptions(options.cache, file.filePath, 'static');
+    const headers = {
+        'content-length': String(file.size),
+        'content-type': getContentType(extension),
+        ...createCacheHeaders(cache, file.size, file.modifiedTime),
+        ...toHeadersObject(typeof options.headers === 'function'
+            ? options.headers({
+                filePath: file.filePath,
+                requestPath,
+                statusCode: 200,
+            })
+            : options.headers),
+    };
+    const notModified = maybeNotModified(event, headers);
+    if (notModified) {
+        return notModified;
+    }
+    if (event.httpMethod === 'HEAD') {
+        return {
+            statusCode: 200,
+            body: '',
+            headers,
+            isBase64Encoded: false,
+        };
+    }
+    const content = await readFile(file.filePath);
+    return {
+        statusCode: 200,
+        body: content.toString(isText ? 'utf8' : 'base64'),
+        headers,
+        isBase64Encoded: !isText,
+    };
+};
+export const useSpa = (directory = 'dist', options = {}) => {
+    const normalizedOptions = normalizeSpaOptions(directory, options);
+    let root;
+    const getRoot = () => (root ??= resolveRoot(normalizedOptions.directory));
+    const readSpaFile = async (event, requestPath) => {
+        const staticRoot = await getRoot();
+        const file = await resolveExistingFile(staticRoot, requestPath, 'index.html');
+        return file ? createFileResult(event, requestPath, file, normalizedOptions) : undefined;
+    };
+    return async (event) => {
+        if (!isSpaMethod(event.httpMethod)) {
+            return methodNotAllowed();
+        }
+        let decodedPath;
+        try {
+            decodedPath = decodeURIComponent(event.path);
+        }
+        catch {
+            return notFound();
+        }
+        try {
+            const realFile = await readSpaFile(event, decodedPath);
+            return realFile ?? (await readSpaFile(event, `/${normalizedOptions.fallback}`)) ?? notFound();
+        }
+        catch {
+            return notFound();
         }
-        return handler({
-            ...event,
-            path: `/${index}`,
-        }, context);
     };
 };

package/use-static.d.ts

@@ -1,2 +1,2 @@
-import type { StaticHandler, StaticOptions } from './types.js';
-export declare const useStatic: (options?: StaticOptions) => StaticHandler;
+import type { StaticHandler, UseStaticOptions } from './types.js';
+export declare const useStatic: (directory?: string, options?: UseStaticOptions) => StaticHandler;

package/use-static.js

@@ -1,45 +1,28 @@
-import { readFile, realpath, stat } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import path from 'node:path';
-const DEFAULT_DIRECTORY = 'dist';
-const DEFAULT_INDEX = 'index.html';
-const DEFAULT_ERROR = '404.html';
+import { createCacheHeaders, maybeNotModified, resolveCacheOptions } from './cache.js';
+import { getContentType, isTextExtension } from './content.js';
+import { resolveExistingFile, resolveRoot } from './file.js';
+import { normalizeStaticOptions } from './options.js';
 const NOT_FOUND_BODY = JSON.stringify({ message: 'Not Found' });
 const METHOD_NOT_ALLOWED_BODY = JSON.stringify({ message: 'Method Not Allowed' });
-const CONTENT_TYPES = {
-    '.css': 'text/css; charset=utf-8',
-    '.csv': 'text/csv; charset=utf-8',
-    '.gif': 'image/gif',
-    '.html': 'text/html; charset=utf-8',
-    '.ico': 'image/x-icon',
-    '.jpeg': 'image/jpeg',
-    '.jpg': 'image/jpeg',
-    '.js': 'text/javascript; charset=utf-8',
-    '.json': 'application/json; charset=utf-8',
-    '.map': 'application/json; charset=utf-8',
-    '.mjs': 'text/javascript; charset=utf-8',
-    '.pdf': 'application/pdf',
-    '.png': 'image/png',
-    '.svg': 'image/svg+xml; charset=utf-8',
-    '.txt': 'text/plain; charset=utf-8',
-    '.webp': 'image/webp',
-    '.woff': 'font/woff',
-    '.woff2': 'font/woff2',
-    '.xml': 'application/xml; charset=utf-8',
+const isStaticMethod = (method) => method === 'GET' || method === 'HEAD';
+const toHeadersObject = (headers) => {
+    if (!headers) {
+        return {};
+    }
+    if (headers instanceof Headers) {
+        return Object.fromEntries(headers.entries());
+    }
+    if (Array.isArray(headers)) {
+        return Object.fromEntries(headers);
+    }
+    return Object.fromEntries(Object.entries(headers).map(([key, value]) => [key, String(value)]));
 };
-const TEXT_TYPES = new Set([
-    '.css',
-    '.csv',
-    '.html',
-    '.js',
-    '.json',
-    '.map',
-    '.mjs',
-    '.svg',
-    '.txt',
-    '.xml',
-]);
-const getContentType = (extension) => CONTENT_TYPES[extension.toLowerCase()] ?? 'application/octet-stream';
-const isTextExtension = (extension) => TEXT_TYPES.has(extension.toLowerCase());
+const mergeCustomHeaders = (headers, customHeaders, context) => ({
+    ...headers,
+    ...toHeadersObject(typeof customHeaders === 'function' ? customHeaders(context) : customHeaders),
+});
 const notFound = (body = NOT_FOUND_BODY, headers) => ({
     statusCode: 404,
     body,
@@ -55,116 +38,77 @@ const methodNotAllowed = () => ({
         'content-type': 'application/json; charset=utf-8',
     },
 });
-const isStaticMethod = (method) => method === 'GET' || method === 'HEAD';
-const isInsideDirectory = (directory, candidate) => {
-    const relative = path.relative(directory, candidate);
-    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
-};
-const normalizeOptions = ({ directory = DEFAULT_DIRECTORY, error = DEFAULT_ERROR, index = DEFAULT_INDEX, }) => ({
-    directory,
-    error,
-    index,
-});
-const createFileResult = async (realFilePath, fileSize, method) => {
-    const extension = path.extname(realFilePath);
+const createFileResult = async (event, requestPath, file, options, statusCode = 200) => {
+    const extension = path.extname(file.filePath);
     const isText = isTextExtension(extension);
-    if (method === 'HEAD') {
+    const cache = resolveCacheOptions(options.cache, file.filePath, 'default');
+    const headers = mergeCustomHeaders({
+        'content-length': String(file.size),
+        'content-type': getContentType(extension),
+        ...createCacheHeaders(cache, file.size, file.modifiedTime),
+    }, options.headers, {
+        filePath: file.filePath,
+        requestPath,
+        statusCode,
+    });
+    const notModified = statusCode === 200 ? maybeNotModified(event, headers) : undefined;
+    if (notModified) {
+        return notModified;
+    }
+    if (event.httpMethod === 'HEAD') {
         return {
-            statusCode: 200,
+            statusCode,
             body: '',
-            headers: {
-                'content-length': String(fileSize),
-                'content-type': getContentType(extension),
-            },
+            headers,
             isBase64Encoded: false,
         };
     }
-    const content = await readFile(realFilePath);
+    const content = await readFile(file.filePath);
     return {
-        statusCode: 200,
+        statusCode,
         body: content.toString(isText ? 'utf8' : 'base64'),
-        headers: {
-            'content-length': String(fileSize),
-            'content-type': getContentType(extension),
-        },
+        headers,
         isBase64Encoded: !isText,
     };
 };
-const readStaticFile = async (root, filePath, method) => {
-    if (!isInsideDirectory(root, filePath)) {
-        return undefined;
-    }
-    const realFilePath = await realpath(filePath);
-    if (!isInsideDirectory(root, realFilePath)) {
-        return undefined;
-    }
-    const fileStat = await stat(realFilePath);
-    if (!fileStat.isFile()) {
-        return undefined;
-    }
-    return createFileResult(realFilePath, fileStat.size, method);
-};
-const readErrorFile = async (root, error, method) => {
-    try {
-        const result = await readStaticFile(root, path.resolve(root, error), method);
-        if (!result) {
-            return notFound();
-        }
-        return {
-            ...result,
-            statusCode: 404,
-        };
-    }
-    catch {
-        return notFound();
-    }
-};
-export const useStatic = (options = {}) => {
-    const { directory, error, index } = normalizeOptions(options);
+export const useStatic = (directory = 'dist', options = {}) => {
+    const normalizedOptions = normalizeStaticOptions(directory, options);
     let root;
-    const getRoot = () => (root ??= realpath(directory));
-    return async (event) => {
-        if (!isStaticMethod(event.httpMethod)) {
-            return methodNotAllowed();
-        }
-        let decodedPath;
-        try {
-            decodedPath = decodeURIComponent(event.path);
-        }
-        catch {
+    const getRoot = () => (root ??= resolveRoot(normalizedOptions.directory));
+    const readFileResult = async (event, requestPath, statusCode = 200) => {
+        const staticRoot = await getRoot();
+        const file = await resolveExistingFile(staticRoot, requestPath, normalizedOptions.index);
+        return file ? createFileResult(event, requestPath, file, normalizedOptions, statusCode) : undefined;
+    };
+    const readNotFoundFile = async (event) => {
+        if (!normalizedOptions.notFound) {
             return notFound();
         }
-        let staticRoot;
         try {
-            staticRoot = await getRoot();
+            const result = await readFileResult(event, `/${normalizedOptions.notFound}`, 404);
+            return result ?? notFound();
         }
         catch {
             return notFound();
         }
-        const requestedPath = decodedPath.replace(/^\/+/, '') || index;
-        const candidate = path.resolve(staticRoot, requestedPath);
-        if (!isInsideDirectory(staticRoot, candidate)) {
-            return readErrorFile(staticRoot, error, event.httpMethod);
+    };
+    return async (event) => {
+        if (!isStaticMethod(event.httpMethod)) {
+            return methodNotAllowed();
         }
-        let filePath = candidate;
+        let decodedPath;
         try {
-            const fileStat = await stat(filePath);
-            if (fileStat.isDirectory()) {
-                filePath = path.join(filePath, index);
-            }
+            decodedPath = decodeURIComponent(event.path);
         }
         catch {
-            return readErrorFile(staticRoot, error, event.httpMethod);
-        }
-        if (!isInsideDirectory(staticRoot, filePath)) {
-            return readErrorFile(staticRoot, error, event.httpMethod);
+            return notFound();
         }
         try {
-            const result = await readStaticFile(staticRoot, filePath, event.httpMethod);
-            return result ?? readErrorFile(staticRoot, error, event.httpMethod);
+            const result = await readFileResult(event, decodedPath);
+            return result ?? readNotFoundFile(event);
         }
         catch {
-            return readErrorFile(staticRoot, error, event.httpMethod);
+            return readNotFoundFile(event);
         }
     };
 };

package/with-static.d.ts

@@ -1,3 +1,3 @@
-import type { StaticMountOptions, StaticRouterApi } from './types.js';
+import type { StaticRouterApi } from './types.js';
 import type { RouterApi } from '@vyriy/router';
-export declare const withStatic: (router: RouterApi, options?: StaticMountOptions) => StaticRouterApi;
+export declare const withStatic: (router: RouterApi) => StaticRouterApi;

package/with-static.js

@@ -1,13 +1,16 @@
+import { useSpa } from './use-spa.js';
 import { useStatic } from './use-static.js';
-const normalizeMount = (path) => {
-    const mount = path.startsWith('/') ? path : `/${path}`;
+const createSpaHandler = useSpa;
+const createStaticHandler = useStatic;
+const normalizeMount = (route) => {
+    const mount = route.startsWith('/') ? route : `/${route}`;
     let end = mount.length;
     while (end > 1 && mount[end - 1] === '/') {
         end--;
     }
     return mount.slice(0, end);
 };
-const toStaticPath = (mount, requestPath) => {
+const toMountedPath = (mount, requestPath) => {
     if (mount === '/') {
         return requestPath;
     }
@@ -20,19 +23,43 @@ const toStaticPath = (mount, requestPath) => {
     return undefined;
 };
 const isStaticMethod = (method) => method === 'GET' || method === 'HEAD';
-const toStaticOptions = (options) => typeof options === 'string' ? { directory: options } : (options ?? {});
-export const withStatic = (router, options) => {
+const createFallbackGuard = () => {
+    let hasFallback = false;
+    return () => {
+        if (hasFallback) {
+            throw new Error('Router fallback already exists!');
+        }
+        hasFallback = true;
+    };
+};
+export const withStatic = (router) => {
     const mounts = [];
-    const createStaticHandler = useStatic;
+    let fallbackHandler;
+    const registerFallback = createFallbackGuard();
+    const addMount = (mount) => {
+        mounts.push(mount);
+        mounts.sort((left, right) => right.route.length - left.route.length);
+    };
     const api = {
         delete(path, handler) {
             router.delete(path, handler);
             return api;
         },
         fallback(handler) {
+            registerFallback();
             router.fallback(handler);
             return api;
         },
+        fallbackSpa(directory, fallbackOptions) {
+            registerFallback();
+            fallbackHandler = createSpaHandler(directory, fallbackOptions);
+            return api;
+        },
+        fallbackStatic(directory, fallbackOptions) {
+            registerFallback();
+            fallbackHandler = createStaticHandler(directory, fallbackOptions);
+            return api;
+        },
         get(path, handler) {
             router.get(path, handler);
             return api;
@@ -58,25 +85,29 @@ export const withStatic = (router, options) => {
                 return result;
             }
             for (const mount of mounts) {
-                const staticPath = toStaticPath(mount.path, event.path);
-                if (staticPath === undefined) {
+                const mountedPath = toMountedPath(mount.route, event.path);
+                if (mountedPath === undefined) {
                     continue;
                 }
-                const staticResult = await mount.handler({
+                return mount.handler({
                     ...event,
-                    path: staticPath,
+                    path: mountedPath,
                 }, {});
-                return staticResult;
             }
-            return result;
+            return fallbackHandler ? fallbackHandler(event, {}) : result;
+        },
+        spa(route, directory, mountOptions) {
+            addMount({
+                handler: createSpaHandler(directory, mountOptions),
+                route: normalizeMount(route),
+            });
+            return api;
         },
-        static(path, mountOptions) {
-            const staticOptions = mountOptions ?? options;
-            mounts.push({
-                handler: createStaticHandler(toStaticOptions(staticOptions)),
-                path: normalizeMount(path),
+        static(route, directory, mountOptions) {
+            addMount({
+                handler: createStaticHandler(directory, mountOptions),
+                route: normalizeMount(route),
             });
-            mounts.sort((left, right) => right.path.length - left.path.length);
             return api;
         },
     };

package/with-spa.d.ts

@@ -1,3 +0,0 @@
-import type { StaticOptions } from './types.js';
-import type { RouterApi } from '@vyriy/router';
-export declare const withSpa: (router: RouterApi, directoryOrOptions?: StaticOptions | string) => RouterApi;

package/with-spa.js

@@ -1,44 +0,0 @@
-import { useSpa } from './use-spa.js';
-const createSpaHandler = useSpa;
-const isStaticMethod = (method) => method === 'GET' || method === 'HEAD';
-export const withSpa = (router, directoryOrOptions = {}) => {
-    const options = typeof directoryOrOptions === 'string' ? { directory: directoryOrOptions } : directoryOrOptions;
-    const spaHandler = createSpaHandler(options);
-    const api = {
-        delete(path, handler) {
-            router.delete(path, handler);
-            return api;
-        },
-        fallback(handler) {
-            router.fallback(handler);
-            return api;
-        },
-        get(path, handler) {
-            router.get(path, handler);
-            return api;
-        },
-        handle() {
-            return (event) => api.route(event);
-        },
-        patch(path, handler) {
-            router.patch(path, handler);
-            return api;
-        },
-        post(path, handler) {
-            router.post(path, handler);
-            return api;
-        },
-        put(path, handler) {
-            router.put(path, handler);
-            return api;
-        },
-        route: async (event) => {
-            const result = await router.route(event);
-            if (result.statusCode !== 404 || !isStaticMethod(event.httpMethod)) {
-                return result;
-            }
-            return spaHandler(event, {});
-        },
-    };
-    return api;
-};