@mastrojs/mastro 0.0.0-stage → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +60 -2
- package/dist/cli.d.ts +3 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +92 -0
- package/dist/core/fs.d.ts +67 -0
- package/dist/core/fs.d.ts.map +1 -0
- package/dist/core/fs.js +114 -0
- package/dist/core/fsHelpers.d.ts +18 -0
- package/dist/core/fsHelpers.d.ts.map +1 -0
- package/dist/core/fsHelpers.js +17 -0
- package/dist/core/html.d.ts +67 -0
- package/dist/core/html.d.ts.map +1 -0
- package/dist/core/html.js +201 -0
- package/dist/core/responses.d.ts +98 -0
- package/dist/core/responses.d.ts.map +1 -0
- package/dist/core/responses.js +145 -0
- package/dist/core/routeHelpers.d.ts +12 -0
- package/dist/core/routeHelpers.d.ts.map +1 -0
- package/dist/core/routeHelpers.js +51 -0
- package/dist/generator.d.ts +16 -0
- package/dist/generator.d.ts.map +1 -0
- package/dist/generator.js +124 -0
- package/dist/index.d.ts +13 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +10 -0
- package/dist/mastro.d.ts +58 -0
- package/dist/mastro.d.ts.map +1 -0
- package/dist/mastro.js +93 -0
- package/dist/middleware.d.ts +4 -0
- package/dist/middleware.d.ts.map +1 -0
- package/dist/middleware.js +21 -0
- package/dist/middlewares/fingerprintAssets.d.ts +3 -0
- package/dist/middlewares/fingerprintAssets.d.ts.map +1 -0
- package/dist/middlewares/fingerprintAssets.js +35 -0
- package/dist/middlewares/logger.d.ts +4 -0
- package/dist/middlewares/logger.d.ts.map +1 -0
- package/dist/middlewares/logger.js +41 -0
- package/dist/middlewares/staticFiles/mediaTypes.d.ts +6 -0
- package/dist/middlewares/staticFiles/mediaTypes.d.ts.map +1 -0
- package/dist/middlewares/staticFiles/mediaTypes.js +26 -0
- package/dist/middlewares/staticFiles/mediaTypes.json +910 -0
- package/dist/middlewares/staticFiles/staticFiles.d.ts +10 -0
- package/dist/middlewares/staticFiles/staticFiles.d.ts.map +1 -0
- package/dist/middlewares/staticFiles/staticFiles.js +119 -0
- package/dist/middlewares/tsToJs.d.ts +13 -0
- package/dist/middlewares/tsToJs.d.ts.map +1 -0
- package/dist/middlewares/tsToJs.js +49 -0
- package/dist/servers/fileRouter.d.ts +11 -0
- package/dist/servers/fileRouter.d.ts.map +1 -0
- package/dist/servers/fileRouter.js +74 -0
- package/dist/servers/fileRoutes.d.ts +2 -0
- package/dist/servers/fileRoutes.d.ts.map +1 -0
- package/dist/servers/fileRoutes.js +1 -0
- package/dist/servers/server.d.ts +22 -0
- package/dist/servers/server.d.ts.map +1 -0
- package/dist/servers/server.js +21 -0
- package/dist/types/mastro.d.ts +80 -0
- package/dist/types/middleware.d.ts +157 -0
- package/dist/types/standard-schema.d.ts +76 -0
- package/package.json +52 -3
- package/src/README.md +29 -0
- package/src/cli.ts +89 -0
- package/src/core/fs.ts +131 -0
- package/src/core/fsHelpers.ts +24 -0
- package/src/core/html.ts +226 -0
- package/src/core/responses.ts +175 -0
- package/src/core/routeHelpers.ts +60 -0
- package/src/generator.ts +139 -0
- package/src/index.ts +14 -0
- package/src/mastro.ts +116 -0
- package/src/middleware.ts +28 -0
- package/src/middlewares/fingerprintAssets.ts +37 -0
- package/src/middlewares/logger.ts +43 -0
- package/src/middlewares/staticFiles/mediaTypes.json +910 -0
- package/src/middlewares/staticFiles/mediaTypes.ts +28 -0
- package/src/middlewares/staticFiles/staticFiles.ts +136 -0
- package/src/middlewares/tsToJs.ts +43 -0
- package/src/servers/fileRouter.ts +83 -0
- package/src/servers/fileRoutes.ts +1 -0
- package/src/servers/server.ts +29 -0
- package/src/types/mastro.d.ts +80 -0
- package/src/types/middleware.d.ts +157 -0
- package/src/types/standard-schema.d.ts +76 -0
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
/** The Standard Schema interface. */
|
|
2
|
+
export interface StandardSchemaV1<Input = unknown, Output = Input> {
|
|
3
|
+
/** The Standard Schema properties. */
|
|
4
|
+
readonly "~standard": StandardSchemaV1.Props<Input, Output>;
|
|
5
|
+
}
|
|
6
|
+
|
|
7
|
+
export declare namespace StandardSchemaV1 {
|
|
8
|
+
/** The Standard Schema properties interface. */
|
|
9
|
+
export interface Props<Input = unknown, Output = Input> {
|
|
10
|
+
/** The version number of the standard. */
|
|
11
|
+
readonly version: 1;
|
|
12
|
+
/** The vendor name of the schema library. */
|
|
13
|
+
readonly vendor: string;
|
|
14
|
+
/** Validates unknown input values. */
|
|
15
|
+
readonly validate: (
|
|
16
|
+
value: unknown,
|
|
17
|
+
options?: StandardSchemaV1.Options | undefined,
|
|
18
|
+
) => Result<Output> | Promise<Result<Output>>;
|
|
19
|
+
/** Inferred types associated with the schema. */
|
|
20
|
+
readonly types?: Types<Input, Output> | undefined;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/** The result interface of the validate function. */
|
|
24
|
+
export type Result<Output> = SuccessResult<Output> | FailureResult;
|
|
25
|
+
|
|
26
|
+
/** The result interface if validation succeeds. */
|
|
27
|
+
export interface SuccessResult<Output> {
|
|
28
|
+
/** The typed output value. */
|
|
29
|
+
readonly value: Output;
|
|
30
|
+
/** A falsy value for `issues` indicates success. */
|
|
31
|
+
readonly issues?: undefined;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
export interface Options {
|
|
35
|
+
/** Explicit support for additional vendor-specific parameters, if needed. */
|
|
36
|
+
readonly libraryOptions?: Record<string, unknown> | undefined;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** The result interface if validation fails. */
|
|
40
|
+
export interface FailureResult {
|
|
41
|
+
/** The issues of failed validation. */
|
|
42
|
+
readonly issues: ReadonlyArray<Issue>;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** The issue interface of the failure output. */
|
|
46
|
+
export interface Issue {
|
|
47
|
+
/** The error message of the issue. */
|
|
48
|
+
readonly message: string;
|
|
49
|
+
/** The path of the issue, if any. */
|
|
50
|
+
readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/** The path segment interface of the issue. */
|
|
54
|
+
export interface PathSegment {
|
|
55
|
+
/** The key representing a path segment. */
|
|
56
|
+
readonly key: PropertyKey;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** The Standard Schema types interface. */
|
|
60
|
+
export interface Types<Input = unknown, Output = Input> {
|
|
61
|
+
/** The input type of the schema. */
|
|
62
|
+
readonly input: Input;
|
|
63
|
+
/** The output type of the schema. */
|
|
64
|
+
readonly output: Output;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/** Infers the input type of a Standard Schema. */
|
|
68
|
+
export type InferInput<Schema extends StandardSchemaV1> = NonNullable<
|
|
69
|
+
Schema["~standard"]["types"]
|
|
70
|
+
>["input"];
|
|
71
|
+
|
|
72
|
+
/** Infers the output type of a Standard Schema. */
|
|
73
|
+
export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<
|
|
74
|
+
Schema["~standard"]["types"]
|
|
75
|
+
>["output"];
|
|
76
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,55 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mastrojs/mastro",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.9.0",
|
|
4
|
+
"description": "No dependencies, no build step. Just a simple web framework and site generator.",
|
|
5
|
+
"bin": {
|
|
6
|
+
"mastro": "./dist/cli.js"
|
|
7
|
+
},
|
|
8
|
+
"homepage": "https://mastrojs.github.io",
|
|
9
|
+
"bugs": "https://github.com/mastrojs/mastro/issues",
|
|
10
|
+
"license": "MIT",
|
|
11
|
+
"repository": {
|
|
12
|
+
"type": "git",
|
|
13
|
+
"url": "git+https://github.com/mastrojs/mastro.git",
|
|
14
|
+
"directory": "libs/mastro"
|
|
15
|
+
},
|
|
16
|
+
"files": [
|
|
17
|
+
"README.md",
|
|
18
|
+
"dist",
|
|
19
|
+
"src",
|
|
20
|
+
"!**/*.test.*",
|
|
21
|
+
"!**/*.bench.*"
|
|
22
|
+
],
|
|
23
|
+
"type": "module",
|
|
24
|
+
"exports": {
|
|
25
|
+
".": {
|
|
26
|
+
"types": "./dist/index.d.ts",
|
|
27
|
+
"default": "./dist/index.js"
|
|
28
|
+
},
|
|
29
|
+
"./generator": {
|
|
30
|
+
"types": "./dist/generator.d.ts",
|
|
31
|
+
"default": "./dist/generator.js"
|
|
32
|
+
},
|
|
33
|
+
"./server": {
|
|
34
|
+
"types": "./dist/servers/server.d.ts",
|
|
35
|
+
"default": "./dist/servers/server.js"
|
|
36
|
+
},
|
|
37
|
+
"./file-routes": {
|
|
38
|
+
"types": "./dist/servers/fileRoutes.d.ts",
|
|
39
|
+
"default": "./dist/servers/fileRoutes.js"
|
|
40
|
+
}
|
|
41
|
+
},
|
|
42
|
+
"publishConfig": {
|
|
43
|
+
"access": "public",
|
|
44
|
+
"directory": "dist",
|
|
45
|
+
"linkDirectory": false
|
|
46
|
+
},
|
|
47
|
+
"engines": {
|
|
48
|
+
"node": ">=24"
|
|
49
|
+
},
|
|
50
|
+
"scripts": {
|
|
51
|
+
"check": "tsc --noEmit",
|
|
52
|
+
"test": "node --test 'src/**/*.test.ts'",
|
|
53
|
+
"bench": "node --experimental-bench --bench 'src/**/*.bench.ts'"
|
|
54
|
+
}
|
|
6
55
|
}
|
package/src/README.md
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
The source code of the Mastro library consists of only ~900 lines of TypeScript.
|
|
2
|
+
<details>
|
|
3
|
+
<summary>including types, but excluding tests, comments, and blank lines</summary>
|
|
4
|
+
|
|
5
|
+
In `libs/mastro/src`:
|
|
6
|
+
|
|
7
|
+
tokei --exclude "*.test.ts" --exclude "*.bench.ts" --exclude "*.d.ts" --output json | jq ".TypeScript.code"
|
|
8
|
+
</details>
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
## Core
|
|
12
|
+
|
|
13
|
+
The `@mastrojs/mastro` package [main entry point](index.ts) exports the [Mastro app class](mastro.ts) (used directly for programmatic routing, and indirectly with the file-based router), as well as the following files from `core/`:
|
|
14
|
+
|
|
15
|
+
- [`fs.ts`](core/fs.ts) contains the `readDir`, `readTextFile`, and `findFiles` functions, that work in both the VSCode extension environment and Deno/Node.js/Bun.
|
|
16
|
+
- [`html.ts`](core/html.ts) contains the `html` tagged template literal to construct properly escaped HTML strings.
|
|
17
|
+
- [`responses.ts`](core/responses.ts) – helper functions to create standard [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) objects.
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
## Middlewares
|
|
21
|
+
|
|
22
|
+
[`middlewares/`](middlewares) contains a few default middlewares (e.g. for handling static files) that are used when running the static site generator or the Node.js server. They are exported under `@mastrojs/server`;
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
## Static site generator and server
|
|
26
|
+
|
|
27
|
+
- [`cli.ts`](cli.ts) contains the command line interface (e.g. `mastro generate`) that calls `generator.ts` internally.
|
|
28
|
+
- [`generator.ts`](generator.ts) contains the static site generation code.
|
|
29
|
+
- [`servers/server.ts`](servers/server.ts) exports helpers suited for starting a Node.js server: `createApp`, `createFileRouterApp` and the default middlewares.
|
package/src/cli.ts
ADDED
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { statSync } from "node:fs";
|
|
3
|
+
import fs from "node:fs/promises";
|
|
4
|
+
import { resolve } from "node:path";
|
|
5
|
+
import { pathToFileURL } from "node:url";
|
|
6
|
+
import { parseArgs, type ParseArgsOptionDescriptor } from "node:util";
|
|
7
|
+
|
|
8
|
+
import type { Mastro } from "./mastro.ts";
|
|
9
|
+
import { generate } from "./generator.ts";
|
|
10
|
+
import { findRoutes } from "./servers/fileRouter.ts";
|
|
11
|
+
|
|
12
|
+
class GenerateError extends Error {}
|
|
13
|
+
|
|
14
|
+
const main = async () => {
|
|
15
|
+
const options: { [opt: string]: ParseArgsOptionDescriptor & { description: string } } = {
|
|
16
|
+
"base-url": {
|
|
17
|
+
description: "Base URL for the synthetic requests, defaults to http://127.0.0.1",
|
|
18
|
+
type: "string",
|
|
19
|
+
},
|
|
20
|
+
output: {
|
|
21
|
+
description: "Name of output folder that will be created, defaults to `generated`",
|
|
22
|
+
type: "string",
|
|
23
|
+
},
|
|
24
|
+
"only-pregenerate": {
|
|
25
|
+
description: "Only pregenerate routes with `pregenerate` set",
|
|
26
|
+
type: "boolean",
|
|
27
|
+
},
|
|
28
|
+
};
|
|
29
|
+
const { values, positionals } = parseArgs({ options, allowPositionals: true });
|
|
30
|
+
switch (positionals[0]) {
|
|
31
|
+
case "generate":
|
|
32
|
+
return mastroGenerate(values);
|
|
33
|
+
case "write-file-routes":
|
|
34
|
+
return writeFileRoutes();
|
|
35
|
+
default: {
|
|
36
|
+
const unknownCmd = positionals[0] !== "help";
|
|
37
|
+
if (unknownCmd) console.info(`'${positionals[0]}' is not a valid mastro command.`);
|
|
38
|
+
const keys = Object.keys(options);
|
|
39
|
+
const maxKeyLen = Math.max(...keys.map((k) => k.length));
|
|
40
|
+
const opts = keys.map(
|
|
41
|
+
(key) => ` --${key.padEnd(maxKeyLen)} ${options[key]?.description}`,
|
|
42
|
+
);
|
|
43
|
+
console.info(`The 'mastro' CLI has the following commands:\n
|
|
44
|
+
generate a static site\n mastro generate [options]\n${opts.join("\n")}\n
|
|
45
|
+
print this help page\n mastro help\n
|
|
46
|
+
write a \`.routes.ts\` file (e.g. for Cloudflare or Service Workers)\n mastro write-routes\n`);
|
|
47
|
+
if (unknownCmd) process.exit(1);
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
};
|
|
51
|
+
|
|
52
|
+
const mastroGenerate = async (values: ReturnType<typeof parseArgs>["values"]) => {
|
|
53
|
+
const serverPath = exists("server.ts") || exists("server.js");
|
|
54
|
+
const example = "`export const app = new Mastro()` or similar.";
|
|
55
|
+
if (!serverPath) {
|
|
56
|
+
throw new GenerateError(`No \`server.ts\` or \`server.js\` found in the project directory root.
|
|
57
|
+
Create one containing ${example}`);
|
|
58
|
+
}
|
|
59
|
+
// if we had https://github.com/nodejs/node/issues/63096, we could start server without server.ts:
|
|
60
|
+
// const app = server ? await import(server).then((m) => m.app as Mastro) : createFileRouterApp();
|
|
61
|
+
const { app } = await import(serverPath);
|
|
62
|
+
if (!app) throw new GenerateError(serverPath + "\nis missing " + example);
|
|
63
|
+
const success = await generate(app as Mastro, {
|
|
64
|
+
baseUrl: values["base-url"] as string | undefined,
|
|
65
|
+
outFolder: values.output as string | undefined,
|
|
66
|
+
onlyPregenerate: !!values["only-pregenerate"],
|
|
67
|
+
});
|
|
68
|
+
if (!success) process.exit(1);
|
|
69
|
+
};
|
|
70
|
+
|
|
71
|
+
const exists = (entry: string) => {
|
|
72
|
+
const path = pathToFileURL(resolve(entry));
|
|
73
|
+
return statSync(path, { throwIfNoEntry: false })?.isFile() ? path.href : undefined;
|
|
74
|
+
};
|
|
75
|
+
|
|
76
|
+
const writeFileRoutes = async () => {
|
|
77
|
+
const contents = `// this file was generated by mastro write-file-routes. Do not edit manually!
|
|
78
|
+
import { loadRoutes } from "@mastrojs/mastro/file-routes";
|
|
79
|
+
|
|
80
|
+
export const routes = loadRoutes(${JSON.stringify(await findRoutes(), null, 2)},
|
|
81
|
+
(name: string) => import(\`./routes/\${name.slice(7, -10)}.server.\${name.slice(-2)}\`),
|
|
82
|
+
);\n`;
|
|
83
|
+
return fs.writeFile(".routes.ts", contents);
|
|
84
|
+
};
|
|
85
|
+
|
|
86
|
+
await main().catch((e) => {
|
|
87
|
+
console.error(`\n${e instanceof GenerateError ? e.message : e}`);
|
|
88
|
+
process.exit(1);
|
|
89
|
+
});
|
package/src/core/fs.ts
ADDED
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Lightweight wrapper around Node.js's file system functions. But for better interoperability
|
|
3
|
+
* with incoming URL paths, input and output paths of these functions use URL encoding.
|
|
4
|
+
*
|
|
5
|
+
* - Implementation uses RPC for the [vscode-extension](../../../../vscode-extension/README.md).
|
|
6
|
+
* - Cloudflare Workers work with Node.js compatibility.
|
|
7
|
+
* - For Service Workers (where there is no filesystem), we fall back to undefined
|
|
8
|
+
* and skip Node.js imports so the module can still load.
|
|
9
|
+
*/
|
|
10
|
+
import type { StandardSchemaV1 } from "../types/standard-schema.d.ts";
|
|
11
|
+
import { normalizeSlashes, sep, urlPathToFilePath } from "./fsHelpers.ts";
|
|
12
|
+
|
|
13
|
+
const nodeFs = "node:fs/promises"; // In a variable to prevent bundling by esbuild
|
|
14
|
+
const cf = "Cloudflare-Workers";
|
|
15
|
+
// @ts-expect-error WorkerGlobalScope
|
|
16
|
+
const worker = typeof self !== "undefined" && self.WorkerGlobalScope && navigator.userAgent !== cf;
|
|
17
|
+
const isWebOrWorker = typeof document === "object" || worker;
|
|
18
|
+
|
|
19
|
+
const fs = isWebOrWorker
|
|
20
|
+
? undefined
|
|
21
|
+
: (import(nodeFs) as Promise<typeof import("node:fs/promises")>);
|
|
22
|
+
const vscodeExtensionFs = typeof document === "object" ? (document as any).fs : undefined;
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* Read the directory on the local file system and return its files,
|
|
26
|
+
* non-recursive and ignoring symlinks and dotfiles.
|
|
27
|
+
*
|
|
28
|
+
* Input is a URL path relative to project root. Returned filenames are URL-encoded.
|
|
29
|
+
*/
|
|
30
|
+
export const readDir = async (path: string): Promise<string[]> => {
|
|
31
|
+
if (!fs) return (await vscodeExtensionFs.readDir(urlPathToFilePath(path))).map(toUrlPath);
|
|
32
|
+
const files = await (await fs).readdir(urlPathToFilePath(path), { withFileTypes: true });
|
|
33
|
+
return files
|
|
34
|
+
.filter((file) => !file.isSymbolicLink() && !file.isDirectory() && file.name[0] !== ".")
|
|
35
|
+
.map((file) => toUrlPath(file.name));
|
|
36
|
+
};
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Return the contents of a text file on the local file system as a string.
|
|
40
|
+
*
|
|
41
|
+
* Input is a URL path relative to project root.
|
|
42
|
+
*/
|
|
43
|
+
export const readTextFile = async (path: string): Promise<string> =>
|
|
44
|
+
fs
|
|
45
|
+
? (await fs).readFile(urlPathToFilePath(path), { encoding: "utf8" })
|
|
46
|
+
: vscodeExtensionFs.readTextFile(urlPathToFilePath(path));
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* Return the contents of a binary file on the local file system.
|
|
50
|
+
*
|
|
51
|
+
* Input is a URL path relative to project root.
|
|
52
|
+
*/
|
|
53
|
+
export const readFile = async (path: string): Promise<Uint8Array<ArrayBufferLike>> =>
|
|
54
|
+
fs
|
|
55
|
+
? (await fs).readFile(urlPathToFilePath(path))
|
|
56
|
+
: vscodeExtensionFs.readFile(urlPathToFilePath(path));
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* Return the file paths on the local file system, relative to the current working directory,
|
|
60
|
+
* expanding glob patterns like `*` and `**`. Do not pass it untrusted input.
|
|
61
|
+
*
|
|
62
|
+
* Returned paths are sorted alphabetically, are URL-encoded, use forward slashes,
|
|
63
|
+
* and don't start with a slash. Input glob patterns use filesystem names, not URL encoding.
|
|
64
|
+
*
|
|
65
|
+
* Except for when using the Mastro VSCode extension, this is a thin wrapper around
|
|
66
|
+
* [fs.glob](https://nodejs.org/api/fs.html#fspromisesglobpattern-options).
|
|
67
|
+
*
|
|
68
|
+
* In [VSCode for the Web](https://code.visualstudio.com/api/references/vscode-api#GlobPattern)
|
|
69
|
+
* there is a [bug](https://github.com/microsoft/vscode/issues/249197) and we had to roll our own.
|
|
70
|
+
*/
|
|
71
|
+
export const findFiles = async (pattern: string | string[]): Promise<string[]> => {
|
|
72
|
+
pattern = typeof pattern === "string" ? validatePattern(pattern) : pattern.map(validatePattern);
|
|
73
|
+
if (!fs) return ((await vscodeExtensionFs.findFiles(pattern)) as string[]).map(toUrlPath).sort();
|
|
74
|
+
const paths: string[] = [];
|
|
75
|
+
for await (const entry of (await fs).glob(pattern, { withFileTypes: true })) {
|
|
76
|
+
if (entry.isFile()) {
|
|
77
|
+
const relativeToCwd = (entry.parentPath + sep + entry.name).slice(process.cwd().length + 1);
|
|
78
|
+
paths.push(toUrlPath(relativeToCwd));
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
return paths.sort();
|
|
82
|
+
};
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Read all files from the local filesystem that match the supplied glob pattern (via `findFiles`)
|
|
86
|
+
* and parse them as JSON. Returns an array with `data`, `path` as a URL path, and `slug` as the
|
|
87
|
+
* URL-encoded filename up to its first dot (e.g. `post.en.json` becomes `post`).
|
|
88
|
+
*
|
|
89
|
+
* The default TypeScript type for the data is `unknown`. You can override that with e.g.
|
|
90
|
+
* `readJsonFiles<{ title: string }>("data/*.json")`. But to actually verify the metadata is
|
|
91
|
+
* correct, you should use a schema. For example using
|
|
92
|
+
* [validate.js](https://github.com/jakelazaroff/validate.js):
|
|
93
|
+
*
|
|
94
|
+
* ```ts
|
|
95
|
+
* import { object, string } from "./validate.js";
|
|
96
|
+
* const schema = object({ title: string });
|
|
97
|
+
* const arr = await readJsonFiles(pattern, { schema });
|
|
98
|
+
* ```
|
|
99
|
+
*/
|
|
100
|
+
export const readJsonFiles = async <T>(
|
|
101
|
+
pattern: string,
|
|
102
|
+
opts: { schema?: StandardSchemaV1<unknown, T> } = {},
|
|
103
|
+
): Promise<Array<{ data: T; path: string; slug: string }>> =>
|
|
104
|
+
Promise.all(
|
|
105
|
+
(await findFiles(pattern)).map(async (path) => {
|
|
106
|
+
let data = JSON.parse(await readTextFile(path));
|
|
107
|
+
if (opts.schema) {
|
|
108
|
+
const res = await opts.schema["~standard"].validate(data);
|
|
109
|
+
if (res.issues) {
|
|
110
|
+
const issues = res.issues.map((i) => `${i.message} (${i.path})`);
|
|
111
|
+
throw Error(`JSON in ${path} did not validate:\n ${issues.join("\n ")}`);
|
|
112
|
+
}
|
|
113
|
+
data = res.value;
|
|
114
|
+
}
|
|
115
|
+
const slug = path.split("/").at(-1)?.split(".").at(0) || "";
|
|
116
|
+
return { data, path, slug };
|
|
117
|
+
}),
|
|
118
|
+
);
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* Best-effort input validation for unix paths
|
|
122
|
+
*/
|
|
123
|
+
const validatePattern = (p: string) => {
|
|
124
|
+
p = p.startsWith("/") ? p.slice(1) : p;
|
|
125
|
+
if (p.split("/").includes("..")) throw Error("findFiles pattern must not include .. segments");
|
|
126
|
+
return p;
|
|
127
|
+
};
|
|
128
|
+
|
|
129
|
+
// normalize and convert a filesystem path to a URL path
|
|
130
|
+
const toUrlPath = (path: string): string =>
|
|
131
|
+
normalizeSlashes(path).split("/").map(encodeURIComponent).join("/");
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Internal branded type of a decoded, project-relative filesystem path.
|
|
3
|
+
*/
|
|
4
|
+
export type FilePath = string & { readonly __filePath: unique symbol };
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Convert a URL path to a decoded, project-relative filesystem path with forward slashes
|
|
8
|
+
* on every platform. For example `urlPathToFilePath("/foo/bar%20baz.jpg") === "foo/bar baz.jpg"`
|
|
9
|
+
*/
|
|
10
|
+
export const urlPathToFilePath = (urlPath: string & { readonly __filePath?: never }): FilePath => {
|
|
11
|
+
const path = normalizeSlashes(decodeURIComponent(urlPath)).replace(/^\/+/, "");
|
|
12
|
+
if (path.split("/").includes("..")) throw Error("FilePath must not include .. segments");
|
|
13
|
+
// on Windows, prevent paths starting with `C:`, `./C:`, etc:
|
|
14
|
+
if (sep === "\\" && /^(?:\.\/+)*[a-z]:/i.test(path)) throw Error("FilePath must be relative");
|
|
15
|
+
return (path || ".") as FilePath; // urlPathToFilePath("/") === "."
|
|
16
|
+
};
|
|
17
|
+
|
|
18
|
+
/** Replace backslashes with forward slashes on Windows */
|
|
19
|
+
export const normalizeSlashes = (path: string): string =>
|
|
20
|
+
sep === "\\" ? path.replaceAll("\\", "/") : path;
|
|
21
|
+
|
|
22
|
+
/** Backslash on Windows, forward slash everywhere else */
|
|
23
|
+
export const sep: "/" | "\\" =
|
|
24
|
+
typeof process !== "undefined" && process.platform === "win32" ? "\\" : "/";
|
package/src/core/html.ts
ADDED
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@mastrojs/mastro/html` contains a selfcontained way to construct and properly escape
|
|
3
|
+
* HTML using JavaScript tagged template literals.
|
|
4
|
+
* All its exports are also exported by the default `@mastrojs/mastro` module,
|
|
5
|
+
* and usually you should just use those. However, it is also exported separately here
|
|
6
|
+
* for use in `@mastrojs/reactive` or other projects where you only want its functionality.
|
|
7
|
+
* @module
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* HTML primitive values like strings and numbers.
|
|
12
|
+
*
|
|
13
|
+
* Note that we use `String` objects to store already properly escaped HTML.
|
|
14
|
+
*/
|
|
15
|
+
export type HtmlPrimitive = String | string | number | undefined | null | false;
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* An `Html` node – i.e. what can be used with `html` tagged templates.
|
|
19
|
+
*/
|
|
20
|
+
export type Html =
|
|
21
|
+
| HtmlPrimitive
|
|
22
|
+
| Html[]
|
|
23
|
+
| AsyncIterable<Html>
|
|
24
|
+
| Promise<Html>;
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Tagged template literal to construct `Html` nodes.
|
|
28
|
+
* This makes sure things are properly escaped (unless `unsafeInnerHtml` is used).
|
|
29
|
+
*
|
|
30
|
+
* ```ts
|
|
31
|
+
* import { html, renderToString } from "@mastrojs/mastro";
|
|
32
|
+
*
|
|
33
|
+
* const myName = "World";
|
|
34
|
+
* const myClass = "hero";
|
|
35
|
+
*
|
|
36
|
+
* const str = await renderToString(
|
|
37
|
+
* html`<h1 class=${myClass}>Hello ${myName}</h1>`
|
|
38
|
+
* );
|
|
39
|
+
* ```
|
|
40
|
+
*/
|
|
41
|
+
export const html = (templateParts: TemplateStringsArray, ...params: Html[]): Html[] => {
|
|
42
|
+
let parts = cache.get(templateParts); // soon we can use cache.getOrInsertComputed
|
|
43
|
+
if (!parts) cache.set(templateParts, parts = parseParts(templateParts));
|
|
44
|
+
const output: Html[] = [];
|
|
45
|
+
for (let i = 0; i < parts.length; i++) {
|
|
46
|
+
const { html, quote } = parts[i]!;
|
|
47
|
+
output.push(html);
|
|
48
|
+
if (i < params.length) {
|
|
49
|
+
const p = params[i];
|
|
50
|
+
if (quote) {
|
|
51
|
+
output.push(unsafeInnerHtml('"'), p, unsafeInnerHtml('"'));
|
|
52
|
+
} else if (Array.isArray(p)) {
|
|
53
|
+
output.push(...p);
|
|
54
|
+
} else {
|
|
55
|
+
output.push(p);
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
return output;
|
|
60
|
+
};
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Mark a string as already properly escaped HTML. Do not use this on an untrusted/user-supplied string!
|
|
64
|
+
*
|
|
65
|
+
* This is similar to the DOM's [innerHTML](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML#replacing_the_contents_of_an_element)
|
|
66
|
+
* or React's `dangerouslySetInnerHTML`.
|
|
67
|
+
*/
|
|
68
|
+
export const unsafeInnerHtml = (val: string): HtmlPrimitive => Object.freeze(new String(val));
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Returns true iff `val` is an async iterable
|
|
72
|
+
*/
|
|
73
|
+
export const isAsyncIterable = <T>(val: any): val is AsyncIterable<T> =>
|
|
74
|
+
val && typeof val[Symbol.asyncIterator] === "function";
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* Convert an `Html` node to a properly escaped `Promise<string>`.
|
|
78
|
+
*
|
|
79
|
+
* See `renderToStream` for a more efficient but less ergonomic alternative.
|
|
80
|
+
*/
|
|
81
|
+
export const renderToString = async (node: Html): Promise<string> => {
|
|
82
|
+
const s = renderToStream(node);
|
|
83
|
+
return typeof s === "string" ? s : (await Array.fromAsync(s)).join("");
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/**
|
|
87
|
+
* Convert an `Html` node to a properly escaped `string` but
|
|
88
|
+
* throws if the input contains a Promise or AsyncIterable.
|
|
89
|
+
* You probably want to use `renderToString` or `renderToStream` instead.
|
|
90
|
+
*/
|
|
91
|
+
export const renderToStringSync = (node: Html): string => {
|
|
92
|
+
const s = renderToStream(Array.isArray(node) ? node : [node]);
|
|
93
|
+
if (typeof s !== "string") {
|
|
94
|
+
throw Error("renderToStringSync received async value. Use renderToString instead.");
|
|
95
|
+
}
|
|
96
|
+
return s;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/**
|
|
100
|
+
* Convert an `Html` node to a properly escaped stream.
|
|
101
|
+
* Returns an `AsyncIterable<string>` if there are Promises or AsyncIterables in the input,
|
|
102
|
+
* otherwise returns a `string`.
|
|
103
|
+
*
|
|
104
|
+
* The string case is a lot more efficient – especially when then passed to
|
|
105
|
+
* Mastro's `htmlResponse`, to construct a `Response`.
|
|
106
|
+
*/
|
|
107
|
+
export const renderToStream = (node: Html): string | AsyncIterable<string> => {
|
|
108
|
+
let stack: Array<Html | AsyncIterator<Html>> = [node];
|
|
109
|
+
if (Array.isArray(node)) {
|
|
110
|
+
stack = node.flat(Infinity as 1);
|
|
111
|
+
if (!(stack.some((n) => n instanceof Promise || isAsyncIterable(n)))) {
|
|
112
|
+
// if there is nothing async, we can speed things up by an order of magnitude like this
|
|
113
|
+
let str = "";
|
|
114
|
+
for (let i = 0; i < stack.length; i++) {
|
|
115
|
+
// in my limited testing, this is faster than `stack.map(escape).join("")`
|
|
116
|
+
str += escape(stack[i] as HtmlPrimitive);
|
|
117
|
+
}
|
|
118
|
+
return str;
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
// reversing and using pop() is faster than using shift().
|
|
123
|
+
// However, we could investigate whether keeping a manual index would be better,
|
|
124
|
+
// but garbage collection would probably suffer.
|
|
125
|
+
stack.reverse();
|
|
126
|
+
|
|
127
|
+
// Set up buffer to reduce per-chunk overhead
|
|
128
|
+
let buffer = "";
|
|
129
|
+
let closed = false;
|
|
130
|
+
const flushBuffer = () => {
|
|
131
|
+
const value = buffer;
|
|
132
|
+
buffer = "";
|
|
133
|
+
return { value, done: false };
|
|
134
|
+
};
|
|
135
|
+
|
|
136
|
+
return {
|
|
137
|
+
[Symbol.asyncIterator]() {
|
|
138
|
+
return {
|
|
139
|
+
next: async () => {
|
|
140
|
+
while (stack.length > 0) {
|
|
141
|
+
const nextUp = stack[stack.length - 1];
|
|
142
|
+
if (buffer.length > 0 &&
|
|
143
|
+
(nextUp instanceof Promise || isAsyncIterable(nextUp) || isAsyncIterator(nextUp))) {
|
|
144
|
+
return flushBuffer();
|
|
145
|
+
}
|
|
146
|
+
if (isAsyncIterator(nextUp)) {
|
|
147
|
+
// If an iterator is on top of the stack, consume its next element:
|
|
148
|
+
const { value, done } = await nextUp.next();
|
|
149
|
+
if (closed) break;
|
|
150
|
+
// But only pop the iterator itself from the stack when it's done:
|
|
151
|
+
done ? stack.pop() : stack.push(value);
|
|
152
|
+
} else {
|
|
153
|
+
const current = await stack.pop();
|
|
154
|
+
if (closed) break;
|
|
155
|
+
if (Array.isArray(current)) {
|
|
156
|
+
for (let i = current.length - 1; i >= 0; i--) {
|
|
157
|
+
stack.push(current[i]);
|
|
158
|
+
}
|
|
159
|
+
} else if (isAsyncIterable(current)) {
|
|
160
|
+
// push iterator on stack for future consumption
|
|
161
|
+
stack.push(current[Symbol.asyncIterator]());
|
|
162
|
+
} else {
|
|
163
|
+
buffer += escape(current as HtmlPrimitive);
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
// stack is emptied, only the buffer may be left
|
|
168
|
+
return buffer.length === 0 || closed
|
|
169
|
+
? { value: undefined, done: true }
|
|
170
|
+
: flushBuffer();
|
|
171
|
+
},
|
|
172
|
+
return: async () => {
|
|
173
|
+
closed = true;
|
|
174
|
+
// Close sequentially from the inside out, continuing even if cleanup throws.
|
|
175
|
+
await stack.splice(0).filter(isAsyncIterator<Html>).reduceRight(
|
|
176
|
+
(cleanup, iterator) => cleanup.finally(() => iterator.return?.()),
|
|
177
|
+
Promise.resolve(),
|
|
178
|
+
);
|
|
179
|
+
return { value: undefined, done: true };
|
|
180
|
+
},
|
|
181
|
+
};
|
|
182
|
+
},
|
|
183
|
+
};
|
|
184
|
+
};
|
|
185
|
+
|
|
186
|
+
/**
|
|
187
|
+
* Parse HTML snippets to determine whether we should wrap the next part in quotes
|
|
188
|
+
* e.g. `<div class=${'myClass'}>`. We don't handle HTML comments, or single-quoted
|
|
189
|
+
* attributes, and track only whether we're in <script> contents (but not <style> etc).
|
|
190
|
+
*/
|
|
191
|
+
const parseParts = (templateParts: TemplateStringsArray) => {
|
|
192
|
+
let inAttr = false, inScript = false;
|
|
193
|
+
let tagContents = ""; // empty string means we're outside a tag
|
|
194
|
+
return templateParts.map((str) => {
|
|
195
|
+
for (let i = 0; i < str.length; i++) {
|
|
196
|
+
const char = str[i];
|
|
197
|
+
if (inScript && str.startsWith("</script>", i)) inScript = false;
|
|
198
|
+
if (inScript) continue;
|
|
199
|
+
if (!tagContents && char !== "<") continue;
|
|
200
|
+
if (char === '"') inAttr = !inAttr;
|
|
201
|
+
tagContents += char;
|
|
202
|
+
if (!inAttr && char === ">") {
|
|
203
|
+
inScript = /^<script(?:\s|>)/.test(tagContents);
|
|
204
|
+
tagContents = "";
|
|
205
|
+
}
|
|
206
|
+
}
|
|
207
|
+
return { html: unsafeInnerHtml(str), quote: !inAttr && /\s[\w:-]+=$/.test(tagContents) };
|
|
208
|
+
});
|
|
209
|
+
};
|
|
210
|
+
|
|
211
|
+
const escape = (n: HtmlPrimitive): string =>
|
|
212
|
+
typeof n === "string"
|
|
213
|
+
? escapeForAttribute(n)
|
|
214
|
+
: (n || typeof n === "number") ? n.toString() : "";
|
|
215
|
+
|
|
216
|
+
const escapeForAttribute = (str: string) =>
|
|
217
|
+
needsEscaping.test(str)
|
|
218
|
+
? str.replace(/[&<>'"]/g, (char) => chars[char as keyof typeof chars])
|
|
219
|
+
: str;
|
|
220
|
+
const needsEscaping = /[&<>'"]/;
|
|
221
|
+
const chars = { "&": "&", "<": "<", ">": ">", "'": "'", '"': """ };
|
|
222
|
+
|
|
223
|
+
const isAsyncIterator = <T>(val: any): val is AsyncIterator<T> =>
|
|
224
|
+
val && typeof val.next === "function";
|
|
225
|
+
|
|
226
|
+
const cache = new Map<TemplateStringsArray, { html: HtmlPrimitive; quote: boolean }[]>();
|