heliumts 0.10.2 → 0.11.1
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/README.md +45 -46
- package/dist/bin/helium.js +117 -172
- package/dist/bin/helium.js.map +1 -1
- package/dist/bin/projectCommands.d.ts +59 -0
- package/dist/bin/projectCommands.d.ts.map +1 -0
- package/dist/bin/projectCommands.js +103 -0
- package/dist/bin/projectCommands.js.map +1 -0
- package/dist/bin/publicApi.d.ts +30 -0
- package/dist/bin/publicApi.d.ts.map +1 -0
- package/dist/bin/publicApi.js +155 -0
- package/dist/bin/publicApi.js.map +1 -0
- package/dist/client/Router.d.ts.map +1 -1
- package/dist/client/Router.js +5 -1
- package/dist/client/Router.js.map +1 -1
- package/dist/client/callMethod.d.ts +2 -2
- package/dist/client/callMethod.d.ts.map +1 -1
- package/dist/client/callMethod.js +3 -2
- package/dist/client/callMethod.js.map +1 -1
- package/dist/client/index.d.ts +3 -1
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/index.js +1 -2
- package/dist/client/index.js.map +1 -1
- package/dist/client/pageModules.d.ts +18 -0
- package/dist/client/pageModules.d.ts.map +1 -0
- package/dist/client/pageModules.js +3 -0
- package/dist/client/pageModules.js.map +1 -0
- package/dist/client/routerManifest.d.ts +2 -11
- package/dist/client/routerManifest.d.ts.map +1 -1
- package/dist/client/routerManifest.js +15 -187
- package/dist/client/routerManifest.js.map +1 -1
- package/dist/client/types.d.ts +12 -12
- package/dist/client/types.d.ts.map +1 -1
- package/dist/client/types.js +8 -1
- package/dist/client/types.js.map +1 -1
- package/dist/client/useCall.d.ts +20 -9
- package/dist/client/useCall.d.ts.map +1 -1
- package/dist/client/useCall.js +21 -6
- package/dist/client/useCall.js.map +1 -1
- package/dist/client/useFetch.d.ts +3 -3
- package/dist/client/useFetch.d.ts.map +1 -1
- package/dist/client/useFetch.js +8 -5
- package/dist/client/useFetch.js.map +1 -1
- package/dist/client/useStreaming.d.ts +3 -3
- package/dist/client/useStreaming.d.ts.map +1 -1
- package/dist/client/useStreaming.js +9 -7
- package/dist/client/useStreaming.js.map +1 -1
- package/dist/internal/index.d.ts +4 -0
- package/dist/internal/index.d.ts.map +1 -0
- package/dist/internal/index.js +4 -0
- package/dist/internal/index.js.map +1 -0
- package/dist/runtime/pageRoutes.d.ts +11 -0
- package/dist/runtime/pageRoutes.d.ts.map +1 -0
- package/dist/runtime/pageRoutes.js +50 -0
- package/dist/runtime/pageRoutes.js.map +1 -0
- package/dist/server/defineMethod.d.ts +16 -2
- package/dist/server/defineMethod.d.ts.map +1 -1
- package/dist/server/defineMethod.js +27 -3
- package/dist/server/defineMethod.js.map +1 -1
- package/dist/server/defineWorker.d.ts.map +1 -1
- package/dist/server/defineWorker.js +4 -6
- package/dist/server/defineWorker.js.map +1 -1
- package/dist/server/devServer.d.ts +2 -1
- package/dist/server/devServer.d.ts.map +1 -1
- package/dist/server/devServer.js +6 -9
- package/dist/server/devServer.js.map +1 -1
- package/dist/server/httpRouter.d.ts.map +1 -1
- package/dist/server/httpRouter.js +17 -2
- package/dist/server/httpRouter.js.map +1 -1
- package/dist/server/index.d.ts +16 -9
- package/dist/server/index.d.ts.map +1 -1
- package/dist/server/index.js +9 -12
- package/dist/server/index.js.map +1 -1
- package/dist/server/prodServer.d.ts +2 -0
- package/dist/server/prodServer.d.ts.map +1 -1
- package/dist/server/prodServer.js +7 -5
- package/dist/server/prodServer.js.map +1 -1
- package/dist/server/ssr.d.ts +4 -1
- package/dist/server/ssr.d.ts.map +1 -1
- package/dist/server/ssr.js +27 -61
- package/dist/server/ssr.js.map +1 -1
- package/dist/vite/heliumPlugin.d.ts +0 -14
- package/dist/vite/heliumPlugin.d.ts.map +1 -1
- package/dist/vite/heliumPlugin.js +68 -294
- package/dist/vite/heliumPlugin.js.map +1 -1
- package/dist/vite/paths.d.ts +0 -2
- package/dist/vite/paths.d.ts.map +1 -1
- package/dist/vite/paths.js +0 -2
- package/dist/vite/paths.js.map +1 -1
- package/dist/vite/rpcDiscovery.d.ts +10 -0
- package/dist/vite/rpcDiscovery.d.ts.map +1 -0
- package/dist/vite/rpcDiscovery.js +237 -0
- package/dist/vite/rpcDiscovery.js.map +1 -0
- package/dist/vite/rpcModule.d.ts +4 -0
- package/dist/vite/rpcModule.d.ts.map +1 -0
- package/dist/vite/rpcModule.js +64 -0
- package/dist/vite/rpcModule.js.map +1 -0
- package/dist/vite/scanner.d.ts +14 -4
- package/dist/vite/scanner.d.ts.map +1 -1
- package/dist/vite/scanner.js +130 -236
- package/dist/vite/scanner.js.map +1 -1
- package/dist/vite/serverClientAdapter.d.ts +103 -0
- package/dist/vite/serverClientAdapter.d.ts.map +1 -0
- package/dist/vite/serverClientAdapter.js +139 -0
- package/dist/vite/serverClientAdapter.js.map +1 -0
- package/dist/vite/ssg.d.ts +5 -8
- package/dist/vite/ssg.d.ts.map +1 -1
- package/dist/vite/ssg.js +32 -263
- package/dist/vite/ssg.js.map +1 -1
- package/dist/vite/virtualServerModule.d.ts +4 -4
- package/dist/vite/virtualServerModule.d.ts.map +1 -1
- package/dist/vite/virtualServerModule.js +18 -62
- package/dist/vite/virtualServerModule.js.map +1 -1
- package/docs/agent/api-reference.md +45 -0
- package/docs/agent/editable-forms.md +37 -0
- package/docs/agent/guide-get.md +13 -0
- package/docs/agent/guide-index.md +15 -0
- package/docs/agent/http-handlers.md +9 -0
- package/docs/agent/imports.md +16 -0
- package/docs/agent/index.md +48 -0
- package/docs/agent/input-validation.md +9 -0
- package/docs/agent/measuring.md +7 -0
- package/docs/agent/mutations.md +11 -0
- package/docs/agent/operations.md +9 -0
- package/docs/agent/query-params.md +28 -0
- package/docs/agent/rendering.md +9 -0
- package/docs/agent/request-context.md +13 -0
- package/docs/agent/routing.md +11 -0
- package/docs/agent/scaffold.md +15 -0
- package/docs/agent/security.md +9 -0
- package/docs/agent/server-files.md +9 -0
- package/docs/agent/streaming.md +9 -0
- package/docs/agent/validation-page.md +21 -0
- package/docs/agent/validation.md +33 -0
- package/docs/agent/verify.md +19 -0
- package/docs/agent/workflow.md +11 -0
- package/docs/agent-guide.md +266 -0
- package/docs/agent-start.md +87 -0
- package/docs/migration-0.11.md +15 -0
- package/package.json +20 -5
- package/dist/server/handlerLoader.d.ts +0 -1
- package/dist/server/handlerLoader.d.ts.map +0 -1
- package/dist/server/handlerLoader.js +0 -2
- package/dist/server/handlerLoader.js.map +0 -1
- package/dist/server/ipExtractor.d.ts +0 -48
- package/dist/server/ipExtractor.d.ts.map +0 -1
- package/dist/server/ipExtractor.js +0 -96
- package/dist/server/ipExtractor.js.map +0 -1
- package/dist/server/requestRouting.d.ts +0 -4
- package/dist/server/requestRouting.d.ts.map +0 -1
- package/dist/server/requestRouting.js +0 -67
- package/dist/server/requestRouting.js.map +0 -1
- package/dist/utils/deepEqual.d.ts +0 -1
- package/dist/utils/deepEqual.d.ts.map +0 -1
- package/dist/utils/deepEqual.js +0 -2
- package/dist/utils/deepEqual.js.map +0 -1
- package/dist/utils/formatError.d.ts +0 -2
- package/dist/utils/formatError.d.ts.map +0 -1
- package/dist/utils/formatError.js +0 -18
- package/dist/utils/formatError.js.map +0 -1
|
@@ -9,7 +9,7 @@ function moduleSpecifier(filePath) {
|
|
|
9
9
|
.replace(/\u2028/g, "\\u2028")
|
|
10
10
|
.replace(/\u2029/g, "\\u2029")}'`;
|
|
11
11
|
}
|
|
12
|
-
export function generateServerManifest(methods, httpHandlers, seoMetadata = [], pageRoutePatterns = [], ssrPages = [], appShellFilePath = null, middleware, workers = []) {
|
|
12
|
+
export function generateServerManifest(methods, httpHandlers, seoMetadata = [], pageRoutePatterns = [], ssrPages = [], appShellFilePath = null, middleware, workers = [], pageRoutes) {
|
|
13
13
|
const methodImports = methods.map((m, i) => `import { ${m.name} as method_${i} } from ${moduleSpecifier(m.filePath)};`).join("\n");
|
|
14
14
|
const httpImports = httpHandlers.map((h, i) => `import { ${h.name} as http_${i} } from ${moduleSpecifier(h.filePath)};`).join("\n");
|
|
15
15
|
const seoImports = seoMetadata.map((s, i) => `import { ${s.name} as seo_${i} } from ${moduleSpecifier(s.filePath)};`).join("\n");
|
|
@@ -81,6 +81,7 @@ ${seoExports}
|
|
|
81
81
|
];
|
|
82
82
|
|
|
83
83
|
export const pageRoutePatterns = ${JSON.stringify(pageRoutePatterns)};
|
|
84
|
+
export const pageRoutes = ${JSON.stringify(pageRoutes?.map(({ pattern, render }) => ({ pattern, render })))};
|
|
84
85
|
|
|
85
86
|
export const ssrPages = [
|
|
86
87
|
${ssrPageExports}
|
|
@@ -100,69 +101,24 @@ ${workerExports}
|
|
|
100
101
|
export const middlewareHandler = ${middleware ? "middleware" : "null"};
|
|
101
102
|
`;
|
|
102
103
|
}
|
|
103
|
-
export function
|
|
104
|
-
const
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
const methodsWithRelativePath = sorted.map((m) => {
|
|
111
|
-
let relPath = path.relative(path.join(root, "src"), m.filePath);
|
|
112
|
-
if (!relPath.startsWith(".")) {
|
|
113
|
-
relPath = "../" + relPath;
|
|
104
|
+
export function generatePageModules(manifest, root) {
|
|
105
|
+
const modules = new Map();
|
|
106
|
+
const importName = (file) => {
|
|
107
|
+
let name = modules.get(file);
|
|
108
|
+
if (!name) {
|
|
109
|
+
name = `pageModule_${modules.size}`;
|
|
110
|
+
modules.set(file, name);
|
|
114
111
|
}
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
112
|
+
return name;
|
|
113
|
+
};
|
|
114
|
+
const entries = manifest.map(({ file, pattern, render, layouts }) => {
|
|
115
|
+
const relativeFile = "/" + path.relative(root, file).split(path.sep).join("/");
|
|
116
|
+
return ` { file: ${JSON.stringify(relativeFile)}, pattern: ${JSON.stringify(pattern)}, render: ${JSON.stringify(render)}, page: ${importName(file)}, layouts: [${layouts
|
|
117
|
+
.map(importName)
|
|
118
|
+
.join(", ")}], preload: () => import(${moduleSpecifier(file)}) },`;
|
|
121
119
|
});
|
|
122
|
-
const imports =
|
|
123
|
-
|
|
124
|
-
return `import type { ${m.name} as __helium_method_${index} } from ${moduleSpecifier(m.relPath)};`;
|
|
125
|
-
})
|
|
126
|
-
.join("\n");
|
|
127
|
-
const methodExports = methodsWithRelativePath
|
|
128
|
-
.map((m, index) => {
|
|
129
|
-
return ` export const ${m.name}: import('heliumts/client').MethodStub<
|
|
130
|
-
Parameters<typeof __helium_method_${index}['handler']>[0],
|
|
131
|
-
Awaited<ReturnType<typeof __helium_method_${index}['handler']>>
|
|
132
|
-
>;`;
|
|
133
|
-
})
|
|
134
|
-
.join("\n");
|
|
135
|
-
// If there are no methods, we don't need to generate any augmentation
|
|
136
|
-
// This prevents shadowing the actual heliumts/server exports
|
|
137
|
-
if (methods.length === 0) {
|
|
138
|
-
return `/* eslint-disable */
|
|
139
|
-
/**
|
|
140
|
-
* Auto generated file - DO NOT EDIT!
|
|
141
|
-
* # Helium Server Type Definitions
|
|
142
|
-
*
|
|
143
|
-
* This file is empty because no methods have been defined yet.
|
|
144
|
-
* Once you create a method using defineMethod(), type stubs will be generated here.
|
|
145
|
-
*
|
|
146
|
-
* @helium-methods (none)
|
|
147
|
-
**/
|
|
148
|
-
export {};
|
|
149
|
-
`;
|
|
150
|
-
}
|
|
151
|
-
const methodSignature = methodsWithRelativePath.map((m) => m.name).join(", ");
|
|
152
|
-
return `/* eslint-disable */
|
|
153
|
-
/**
|
|
154
|
-
* Auto generated file - DO NOT EDIT!
|
|
155
|
-
* # Helium Server Type Definitions
|
|
156
|
-
*
|
|
157
|
-
* @helium-methods ${methodSignature}
|
|
158
|
-
**/
|
|
159
|
-
${imports}
|
|
160
|
-
|
|
161
|
-
declare module 'heliumts/server' {
|
|
162
|
-
// Method stubs for client-side type inference
|
|
163
|
-
${methodExports}
|
|
164
|
-
}
|
|
165
|
-
`;
|
|
120
|
+
const imports = Array.from(modules, ([file, name]) => `import * as ${name} from ${moduleSpecifier(file)};`);
|
|
121
|
+
return `${imports.join("\n")}\nexport const pageModules = [\n${entries.join("\n")}\n];`;
|
|
166
122
|
}
|
|
167
123
|
export function generateEntryModule(appShellFilePath = "/src/App") {
|
|
168
124
|
return `
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"virtualServerModule.js","sourceRoot":"","sources":["../../src/vite/virtualServerModule.ts"],"names":[],"mappings":"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","sourcesContent":["import path from \"path\";\n\nimport { HTTPHandlerExport, MethodExport, MiddlewareExport, SEOMetadataExport, SSRPageExport, WorkerExport } from \"./scanner.js\";\n\nfunction moduleSpecifier(filePath: string): string {\n // Vite expects POSIX import paths, including on Windows.\n return `'${filePath\n .replace(/\\\\/g, \"/\")\n .replace(/'/g, \"\\\\'\")\n .replace(/\\r/g, \"\\\\r\")\n .replace(/\\n/g, \"\\\\n\")\n .replace(/\\u2028/g, \"\\\\u2028\")\n .replace(/\\u2029/g, \"\\\\u2029\")}'`;\n}\n\nexport function generateServerManifest(\n methods: MethodExport[],\n httpHandlers: HTTPHandlerExport[],\n seoMetadata: SEOMetadataExport[] = [],\n pageRoutePatterns: string[] = [],\n ssrPages: SSRPageExport[] = [],\n appShellFilePath: string | null = null,\n middleware?: MiddlewareExport,\n workers: WorkerExport[] = []\n): string {\n const methodImports = methods.map((m, i) => `import { ${m.name} as method_${i} } from ${moduleSpecifier(m.filePath)};`).join(\"\\n\");\n const httpImports = httpHandlers.map((h, i) => `import { ${h.name} as http_${i} } from ${moduleSpecifier(h.filePath)};`).join(\"\\n\");\n const seoImports = seoMetadata.map((s, i) => `import { ${s.name} as seo_${i} } from ${moduleSpecifier(s.filePath)};`).join(\"\\n\");\n const workerImports = workers.map((w, i) => `import { ${w.name} as worker_${i} } from ${moduleSpecifier(w.filePath)};`).join(\"\\n\");\n const middlewareImport = middleware\n ? `import ${middleware.name === \"default\" ? \"middleware\" : `{ ${middleware.name} as middleware }`} from ${moduleSpecifier(middleware.filePath)};`\n : \"\";\n\n const methodRegistrations = methods.map((m, i) => ` registry.register('${m.name}', method_${i});`).join(\"\\n\");\n\n const httpExports = httpHandlers.map((h, i) => ` { name: '${h.name}', handler: http_${i} },`).join(\"\\n\");\n const seoExports = seoMetadata.map((s, i) => ` { name: '${s.name}', handler: seo_${i} },`).join(\"\\n\");\n\n const workerExports = workers.map((w, i) => ` { name: '${w.name}', worker: worker_${i} },`).join(\"\\n\");\n\n const ssrPageExports = ssrPages\n .map((s) => {\n const loadLayoutsBody = s.layoutFilePaths\n .map(\n (layoutPath, layoutIndex) => ` {\n const mod_${layoutIndex} = await import(${moduleSpecifier(layoutPath)});\n if (mod_${layoutIndex}.default) {\n layouts.push(mod_${layoutIndex}.default);\n }\n }`\n )\n .join(\"\\n\");\n\n const sidecarCheck = s.serverFilePath\n ? ` {\n const sidecar = await import(${moduleSpecifier(s.serverFilePath)});\n if (typeof sidecar.getServerSideProps === 'function') {\n return sidecar.getServerSideProps(req, ctx);\n }\n }\n`\n : \"\";\n\n return ` {\n pathPattern: ${JSON.stringify(s.pathPattern)},\n loadComponent: async () => {\n const page = await import(${moduleSpecifier(s.pageFilePath)});\n return page.default;\n },\n loadLayouts: async () => {\n const layouts = [];\n${loadLayoutsBody}\n return layouts;\n },\n getServerSideProps: async (req, ctx) => {\n${sidecarCheck} const page = await import(${moduleSpecifier(s.pageFilePath)});\n if (typeof page.getServerSideProps === 'function') {\n return page.getServerSideProps(req, ctx);\n }\n return null;\n }\n },`;\n })\n .join(\"\\n\");\n\n return `\n${methodImports}\n${httpImports}\n${seoImports}\n${workerImports}\n${middlewareImport}\n\nexport function registerAll(registry) {\n${methodRegistrations}\n}\n\nexport const httpHandlers = [\n${httpExports}\n];\n\nexport const seoMetadataHandlers = [\n${seoExports}\n];\n\nexport const pageRoutePatterns = ${JSON.stringify(pageRoutePatterns)};\n\nexport const ssrPages = [\n${ssrPageExports}\n];\n\nexport const appShell = ${\n appShellFilePath\n ? `async () => {\n const mod = await import(${moduleSpecifier(appShellFilePath)});\n return mod.default ?? mod.App ?? mod.app ?? null;\n}`\n : \"null\"\n };\n\nexport const workers = [\n${workerExports}\n];\n\nexport const middlewareHandler = ${middleware ? \"middleware\" : \"null\"};\n`;\n}\n\nexport function generateClientModule(methods: MethodExport[]): string {\n const exports = methods.map((m) => `export const ${m.name} = { __id: '${m.name}' };`).join(\"\\n\");\n\n return exports;\n}\n\nexport function generateTypeDefinitions(methods: MethodExport[], root: string): string {\n // Sort methods by name for a stable output regardless of file-system walk order\n const sorted = [...methods].sort((a, b) => a.name.localeCompare(b.name));\n\n const methodsWithRelativePath = sorted.map((m) => {\n let relPath = path.relative(path.join(root, \"src\"), m.filePath);\n if (!relPath.startsWith(\".\")) {\n relPath = \"../\" + relPath;\n }\n // Normalize to posix separators for import paths\n relPath = relPath.replace(/\\\\/g, \"/\").replace(/\\.ts$/, \"\");\n return {\n ...m,\n relPath,\n };\n });\n\n const imports = methodsWithRelativePath\n .map((m, index) => {\n return `import type { ${m.name} as __helium_method_${index} } from ${moduleSpecifier(m.relPath)};`;\n })\n .join(\"\\n\");\n\n const methodExports = methodsWithRelativePath\n .map((m, index) => {\n return ` export const ${m.name}: import('heliumts/client').MethodStub<\n Parameters<typeof __helium_method_${index}['handler']>[0],\n Awaited<ReturnType<typeof __helium_method_${index}['handler']>>\n >;`;\n })\n .join(\"\\n\");\n\n // If there are no methods, we don't need to generate any augmentation\n // This prevents shadowing the actual heliumts/server exports\n if (methods.length === 0) {\n return `/* eslint-disable */\n/**\n* Auto generated file - DO NOT EDIT!\n* # Helium Server Type Definitions\n* \n* This file is empty because no methods have been defined yet.\n* Once you create a method using defineMethod(), type stubs will be generated here.\n*\n* @helium-methods (none)\n**/\nexport {};\n`;\n }\n\n const methodSignature = methodsWithRelativePath.map((m) => m.name).join(\", \");\n\n return `/* eslint-disable */\n/**\n* Auto generated file - DO NOT EDIT!\n* # Helium Server Type Definitions\n*\n* @helium-methods ${methodSignature}\n**/\n${imports}\n\ndeclare module 'heliumts/server' {\n // Method stubs for client-side type inference\n${methodExports}\n}\n`;\n}\n\nexport function generateEntryModule(appShellFilePath: string | null = \"/src/App\"): string {\n return `\nimport React from 'react';\nimport { createRoot, hydrateRoot } from 'react-dom/client';\nimport { AppRouter } from 'heliumts/client';\n${appShellFilePath ? `import App from ${moduleSpecifier(appShellFilePath)};` : \"\"}\n\nconst rootEl = document.getElementById('root');\nif (!rootEl) {\n throw new Error('Root element not found. Helium requires a <div id=\"root\"></div> in your HTML.');\n}\n\nconst app = (\n <React.StrictMode>\n <AppRouter${appShellFilePath ? \" AppShell={App}\" : \"\"} />\n </React.StrictMode>\n);\n\nif (rootEl.hasChildNodes()) {\n hydrateRoot(rootEl, app);\n} else {\n createRoot(rootEl).render(app);\n}\n`;\n}\n"]}
|
|
1
|
+
{"version":3,"file":"virtualServerModule.js","sourceRoot":"","sources":["../../src/vite/virtualServerModule.ts"],"names":[],"mappings":"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","sourcesContent":["import path from \"path\";\n\nimport type { PageRoute } from \"../runtime/pageRoutes.js\";\nimport { HTTPHandlerExport, MethodExport, MiddlewareExport, PageManifestEntry, SEOMetadataExport, SSRPageExport, WorkerExport } from \"./scanner.js\";\n\nfunction moduleSpecifier(filePath: string): string {\n // Vite expects POSIX import paths, including on Windows.\n return `'${filePath\n .replace(/\\\\/g, \"/\")\n .replace(/'/g, \"\\\\'\")\n .replace(/\\r/g, \"\\\\r\")\n .replace(/\\n/g, \"\\\\n\")\n .replace(/\\u2028/g, \"\\\\u2028\")\n .replace(/\\u2029/g, \"\\\\u2029\")}'`;\n}\n\nexport function generateServerManifest(\n methods: MethodExport[],\n httpHandlers: HTTPHandlerExport[],\n seoMetadata: SEOMetadataExport[] = [],\n pageRoutePatterns: string[] = [],\n ssrPages: SSRPageExport[] = [],\n appShellFilePath: string | null = null,\n middleware?: MiddlewareExport,\n workers: WorkerExport[] = [],\n pageRoutes?: readonly PageRoute[]\n): string {\n const methodImports = methods.map((m, i) => `import { ${m.name} as method_${i} } from ${moduleSpecifier(m.filePath)};`).join(\"\\n\");\n const httpImports = httpHandlers.map((h, i) => `import { ${h.name} as http_${i} } from ${moduleSpecifier(h.filePath)};`).join(\"\\n\");\n const seoImports = seoMetadata.map((s, i) => `import { ${s.name} as seo_${i} } from ${moduleSpecifier(s.filePath)};`).join(\"\\n\");\n const workerImports = workers.map((w, i) => `import { ${w.name} as worker_${i} } from ${moduleSpecifier(w.filePath)};`).join(\"\\n\");\n const middlewareImport = middleware\n ? `import ${middleware.name === \"default\" ? \"middleware\" : `{ ${middleware.name} as middleware }`} from ${moduleSpecifier(middleware.filePath)};`\n : \"\";\n\n const methodRegistrations = methods.map((m, i) => ` registry.register('${m.name}', method_${i});`).join(\"\\n\");\n\n const httpExports = httpHandlers.map((h, i) => ` { name: '${h.name}', handler: http_${i} },`).join(\"\\n\");\n const seoExports = seoMetadata.map((s, i) => ` { name: '${s.name}', handler: seo_${i} },`).join(\"\\n\");\n\n const workerExports = workers.map((w, i) => ` { name: '${w.name}', worker: worker_${i} },`).join(\"\\n\");\n\n const ssrPageExports = ssrPages\n .map((s) => {\n const loadLayoutsBody = s.layoutFilePaths\n .map(\n (layoutPath, layoutIndex) => ` {\n const mod_${layoutIndex} = await import(${moduleSpecifier(layoutPath)});\n if (mod_${layoutIndex}.default) {\n layouts.push(mod_${layoutIndex}.default);\n }\n }`\n )\n .join(\"\\n\");\n\n const sidecarCheck = s.serverFilePath\n ? ` {\n const sidecar = await import(${moduleSpecifier(s.serverFilePath)});\n if (typeof sidecar.getServerSideProps === 'function') {\n return sidecar.getServerSideProps(req, ctx);\n }\n }\n`\n : \"\";\n\n return ` {\n pathPattern: ${JSON.stringify(s.pathPattern)},\n loadComponent: async () => {\n const page = await import(${moduleSpecifier(s.pageFilePath)});\n return page.default;\n },\n loadLayouts: async () => {\n const layouts = [];\n${loadLayoutsBody}\n return layouts;\n },\n getServerSideProps: async (req, ctx) => {\n${sidecarCheck} const page = await import(${moduleSpecifier(s.pageFilePath)});\n if (typeof page.getServerSideProps === 'function') {\n return page.getServerSideProps(req, ctx);\n }\n return null;\n }\n },`;\n })\n .join(\"\\n\");\n\n return `\n${methodImports}\n${httpImports}\n${seoImports}\n${workerImports}\n${middlewareImport}\n\nexport function registerAll(registry) {\n${methodRegistrations}\n}\n\nexport const httpHandlers = [\n${httpExports}\n];\n\nexport const seoMetadataHandlers = [\n${seoExports}\n];\n\nexport const pageRoutePatterns = ${JSON.stringify(pageRoutePatterns)};\nexport const pageRoutes = ${JSON.stringify(pageRoutes?.map(({ pattern, render }) => ({ pattern, render })))};\n\nexport const ssrPages = [\n${ssrPageExports}\n];\n\nexport const appShell = ${\n appShellFilePath\n ? `async () => {\n const mod = await import(${moduleSpecifier(appShellFilePath)});\n return mod.default ?? mod.App ?? mod.app ?? null;\n}`\n : \"null\"\n };\n\nexport const workers = [\n${workerExports}\n];\n\nexport const middlewareHandler = ${middleware ? \"middleware\" : \"null\"};\n`;\n}\n\nexport function generatePageModules(manifest: readonly PageManifestEntry[], root: string): string {\n const modules = new Map<string, string>();\n const importName = (file: string) => {\n let name = modules.get(file);\n if (!name) {\n name = `pageModule_${modules.size}`;\n modules.set(file, name);\n }\n return name;\n };\n const entries = manifest.map(({ file, pattern, render, layouts }) => {\n const relativeFile = \"/\" + path.relative(root, file).split(path.sep).join(\"/\");\n return ` { file: ${JSON.stringify(relativeFile)}, pattern: ${JSON.stringify(pattern)}, render: ${JSON.stringify(render)}, page: ${importName(file)}, layouts: [${layouts\n .map(importName)\n .join(\", \")}], preload: () => import(${moduleSpecifier(file)}) },`;\n });\n const imports = Array.from(modules, ([file, name]) => `import * as ${name} from ${moduleSpecifier(file)};`);\n return `${imports.join(\"\\n\")}\\nexport const pageModules = [\\n${entries.join(\"\\n\")}\\n];`;\n}\n\nexport function generateEntryModule(appShellFilePath: string | null = \"/src/App\"): string {\n return `\nimport React from 'react';\nimport { createRoot, hydrateRoot } from 'react-dom/client';\nimport { AppRouter } from 'heliumts/client';\n${appShellFilePath ? `import App from ${moduleSpecifier(appShellFilePath)};` : \"\"}\n\nconst rootEl = document.getElementById('root');\nif (!rootEl) {\n throw new Error('Root element not found. Helium requires a <div id=\"root\"></div> in your HTML.');\n}\n\nconst app = (\n <React.StrictMode>\n <AppRouter${appShellFilePath ? \" AppShell={App}\" : \"\"} />\n </React.StrictMode>\n);\n\nif (rootEl.hasChildNodes()) {\n hydrateRoot(rootEl, app);\n} else {\n createRoot(rootEl).render(app);\n}\n`;\n}\n"]}
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# Find installed public API types
|
|
2
|
+
|
|
3
|
+
HeliumTS 0.11.0 application reference. Use matching framework and scaffolder versions; see the upgrade notes when migrating from 0.10.2.
|
|
4
|
+
|
|
5
|
+
Prerequisites: [Keep imports at the right boundary](./imports.md)
|
|
6
|
+
|
|
7
|
+
Use public imports from heliumts/client and heliumts/server. Look up one exact exported symbol in the installed package without loading application modules:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npx helium api useCall --json
|
|
11
|
+
npx helium api useRouter --from client --json
|
|
12
|
+
npx helium api defineMethod --from server --json
|
|
13
|
+
npx helium api UseCallOptions --from client --json
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
If you do not know a symbol name, discover public names first:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npx helium api --list --from client --match router --json
|
|
20
|
+
npx helium api --list --from server --match method --json
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Then look up one returned name. --match requires --list and matches a case-insensitive literal name fragment, not a regular expression. A symbol lookup and --list cannot be combined. Listings are sorted, include public aliases and type exports, and report an empty array when nothing matches. Declaration kinds do not imply runtime availability: an export may be type-only. More than 100 matches or 16 KiB of output fails with a request to narrow the filter; results are never silently truncated.
|
|
24
|
+
|
|
25
|
+
The default entrypoint is client. The result retains overloads, generics and documentation comments, with declaration source paths and related public type names for follow-up queries. Unexported local type shapes are included one level deep for reference, not as import suggestions. Other local, built-in and external references may remain; excerpts are not standalone code. The public module and selected name identify the supported import, even when the declaration uses a different internal alias. Output is capped at 16 KiB; missing, private or oversized lookups fail explicitly. This tool reads this installed framework's declarations, not application-generated RPC methods (use inspect --rpc for those).
|
|
26
|
+
|
|
27
|
+
If needed, open only the relevant declaration in the installed package:
|
|
28
|
+
|
|
29
|
+
- Client exports: node_modules/heliumts/dist/client/index.d.ts.
|
|
30
|
+
- Read and mutation hooks: node_modules/heliumts/dist/client/useFetch.d.ts and node_modules/heliumts/dist/client/useCall.d.ts.
|
|
31
|
+
- Router state and navigation: node_modules/heliumts/dist/client/Router.d.ts.
|
|
32
|
+
- Server exports: node_modules/heliumts/dist/server/index.d.ts.
|
|
33
|
+
- Request context and method options: node_modules/heliumts/dist/server/context.d.ts and node_modules/heliumts/dist/server/defineMethod.d.ts.
|
|
34
|
+
|
|
35
|
+
For a symbol search, restrict output to declarations:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
rg -n -g '*.d.ts' 'useRouter|useCall' node_modules/heliumts/dist/client
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Avoid recursively searching generated JavaScript or source maps for API signatures; those files can produce very large tool outputs.
|
|
42
|
+
|
|
43
|
+
These are files to read, not application deep-import paths. There is no dist/client/hooks directory. Longer docs linked on the source repository are not all shipped in the npm package; use this task index and the installed declarations first. Check the installed package version before relying on external examples.
|
|
44
|
+
|
|
45
|
+
Related: [Use request context safely](./request-context.md), [Navigate with file routes](./routing.md).
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Edit fetched data without a synchronization effect
|
|
2
|
+
|
|
3
|
+
HeliumTS 0.11.0 application reference. Use matching framework and scaffolder versions; see the upgrade notes when migrating from 0.10.2.
|
|
4
|
+
|
|
5
|
+
Prerequisites: [Call a validated method from a page](./validation-page.md), [Mutate and invalidate data](./mutations.md)
|
|
6
|
+
|
|
7
|
+
Pass a loaded article into this component. The app must already define getArticle({ id }), listArticles() and saveArticle({ id, title }) with server-side validation and authorization. The detail parent should show its loading, error and not-found states before rendering the editor.
|
|
8
|
+
|
|
9
|
+
```tsx file=src/components/ArticleEditor.tsx
|
|
10
|
+
import { useState, type FormEvent } from "react";
|
|
11
|
+
import { useCall } from "heliumts/client";
|
|
12
|
+
import { getArticle, listArticles, saveArticle } from "../rpc.generated";
|
|
13
|
+
|
|
14
|
+
type Article = { id: string; title: string };
|
|
15
|
+
|
|
16
|
+
export default function ArticleEditor({ article }: { article: Article }) {
|
|
17
|
+
const save = useCall(saveArticle, { invalidate: [getArticle, listArticles] });
|
|
18
|
+
const [draft, setDraft] = useState<Article | null>(null);
|
|
19
|
+
const title = draft?.id === article.id ? draft.title : article.title;
|
|
20
|
+
|
|
21
|
+
async function submit(event: FormEvent<HTMLFormElement>) {
|
|
22
|
+
event.preventDefault();
|
|
23
|
+
const outcome = await save.submit({ id: article.id, title });
|
|
24
|
+
if (outcome.status === "success") setDraft(null);
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
return <form onSubmit={submit}>
|
|
28
|
+
<label>Title <input value={title} onChange={(event) => setDraft({ id: article.id, title: event.currentTarget.value })} disabled={save.isCalling} required /></label>
|
|
29
|
+
{save.error && <p role="alert">{save.error}</p>}
|
|
30
|
+
<button type="submit" disabled={save.isCalling}>Save</button>
|
|
31
|
+
</form>;
|
|
32
|
+
}
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
The displayed title comes from the current record until the user edits it. A draft is scoped to its record ID, so changing records does not display the previous record's draft. This avoids copying fetched data into state in a useEffect. Clear the draft only after a successful save; retain it when saving fails. The two invalidations refresh both the detail and its list.
|
|
36
|
+
|
|
37
|
+
Related: [Read and cache data](./operations.md).
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Read one guide
|
|
2
|
+
|
|
3
|
+
HeliumTS 0.11.0 application reference. Use matching framework and scaffolder versions; see the upgrade notes when migrating from 0.10.2.
|
|
4
|
+
|
|
5
|
+
Prerequisites: [Open the guide index](./guide-index.md)
|
|
6
|
+
|
|
7
|
+
Open the Markdown file linked from the index. For example, the validation guide contains the complete server method example:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
cat node_modules/heliumts/docs/agent/validation.md
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Read the whole short guide so prerequisites, complete examples and related links stay together. Each guide includes its release warning and belongs to the installed framework package. Check node_modules/heliumts/package.json if you need the exact installed version. Follow prerequisite links only when the task needs that background; use the full compact reference for a task spanning several subjects.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Open the guide index
|
|
2
|
+
|
|
3
|
+
HeliumTS 0.11.0 application reference. Use matching framework and scaffolder versions; see the upgrade notes when migrating from 0.10.2.
|
|
4
|
+
|
|
5
|
+
Prerequisites: None beyond an installed HeliumTS app.
|
|
6
|
+
|
|
7
|
+
Read the Markdown index shipped with the installed framework:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
cat node_modules/heliumts/docs/agent/index.md
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
The index groups 22 focused task guides by subject and links directly to their Markdown files. Choose only the guide needed for the current task. The full compact reference remains at node_modules/heliumts/docs/agent-guide.md.
|
|
14
|
+
|
|
15
|
+
Related: [Read one guide](./guide-get.md).
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Choose an explicit HTTP endpoint
|
|
2
|
+
|
|
3
|
+
HeliumTS 0.11.0 application reference. Use matching framework and scaffolder versions; see the upgrade notes when migrating from 0.10.2.
|
|
4
|
+
|
|
5
|
+
Prerequisites: [Keep imports at the right boundary](./imports.md), [Place discoverable server files](./server-files.md)
|
|
6
|
+
|
|
7
|
+
defineHTTPRequest is for explicit HTTP endpoints, webhooks and integrations. Do not replace ordinary RPC with hand-written transport glue unless the task requires it.
|
|
8
|
+
|
|
9
|
+
Related: [Preserve application security](./security.md).
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Keep imports at the right boundary
|
|
2
|
+
|
|
3
|
+
HeliumTS 0.11.0 application reference. Use matching framework and scaffolder versions; see the upgrade notes when migrating from 0.10.2.
|
|
4
|
+
|
|
5
|
+
Prerequisites: None beyond an installed HeliumTS app.
|
|
6
|
+
|
|
7
|
+
- Import hooks, `Link` and router APIs from `heliumts/client`.
|
|
8
|
+
- Define server methods and middleware with primitives from `heliumts/server`.
|
|
9
|
+
- In browser application files, import RPC method references from the generated `src/rpc.generated.ts` module. For a page in `src/pages/`, use `../rpc.generated`. Pass the reference to a client hook or call helper to infer the method's arguments and result.
|
|
10
|
+
- Never import src/server implementations directly into browser files. Keep credentials, database clients and authorization on the server.
|
|
11
|
+
- Generated server bundles use heliumts/internal for framework helpers; application code should not import this internal entry point. Older helper exports from heliumts/server remain compatible.
|
|
12
|
+
- Use heliumts/vite only in build configuration. The package root is a namespace convenience, not the preferred browser import.
|
|
13
|
+
|
|
14
|
+
When upgrading from 0.10.2, switch browser RPC imports from `heliumts/server` to your generated module, delete the old generated `src/types/heliumts-server.d.ts` if it exists, and run `npx helium check`.
|
|
15
|
+
|
|
16
|
+
Related: [Place discoverable server files](./server-files.md), [Call a validated method from a page](./validation-page.md).
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# HeliumTS task guide index
|
|
2
|
+
|
|
3
|
+
HeliumTS 0.11.0 application reference. Use matching framework and scaffolder versions; see the upgrade notes when migrating from 0.10.2.
|
|
4
|
+
|
|
5
|
+
Read the app's AGENTS.md, then open only the Markdown guide needed using the links below.
|
|
6
|
+
|
|
7
|
+
## Start and verify
|
|
8
|
+
|
|
9
|
+
- workflow: [Orient in an installed app](./workflow.md)
|
|
10
|
+
- scaffold: [Scaffold a minimal app](./scaffold.md)
|
|
11
|
+
- verify: [Verify an application](./verify.md)
|
|
12
|
+
- guide-index: [Open the guide index](./guide-index.md)
|
|
13
|
+
- guide-get: [Read one guide](./guide-get.md)
|
|
14
|
+
|
|
15
|
+
## Imports and files
|
|
16
|
+
|
|
17
|
+
- imports: [Keep imports at the right boundary](./imports.md)
|
|
18
|
+
- api-reference: [Find installed public API types](./api-reference.md)
|
|
19
|
+
- server-files: [Place discoverable server files](./server-files.md)
|
|
20
|
+
|
|
21
|
+
## One validated method and page
|
|
22
|
+
|
|
23
|
+
- validation: [Define one validated method](./validation.md)
|
|
24
|
+
- input-validation: [Understand input parser behavior](./input-validation.md)
|
|
25
|
+
- request-context: [Use request context safely](./request-context.md)
|
|
26
|
+
- validation-page: [Call a validated method from a page](./validation-page.md)
|
|
27
|
+
|
|
28
|
+
## Choose one operation
|
|
29
|
+
|
|
30
|
+
- operations: [Read and cache data](./operations.md)
|
|
31
|
+
- mutations: [Mutate and invalidate data](./mutations.md)
|
|
32
|
+
- editable-forms: [Edit fetched data without a synchronization effect](./editable-forms.md)
|
|
33
|
+
- streaming: [Consume an HTTP stream](./streaming.md)
|
|
34
|
+
- http-handlers: [Choose an explicit HTTP endpoint](./http-handlers.md)
|
|
35
|
+
|
|
36
|
+
## Routing and navigation
|
|
37
|
+
|
|
38
|
+
- routing: [Navigate with file routes](./routing.md)
|
|
39
|
+
- query-params: [Read and update query parameters](./query-params.md)
|
|
40
|
+
|
|
41
|
+
## Rendering and security
|
|
42
|
+
|
|
43
|
+
- rendering: [Choose a rendering mode](./rendering.md)
|
|
44
|
+
- security: [Preserve application security](./security.md)
|
|
45
|
+
|
|
46
|
+
## Measuring AI efficiency
|
|
47
|
+
|
|
48
|
+
- measuring: [Measure successful agent tasks](./measuring.md)
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Understand input parser behavior
|
|
2
|
+
|
|
3
|
+
HeliumTS 0.11.0 application reference. Use matching framework and scaffolder versions; see the upgrade notes when migrating from 0.10.2.
|
|
4
|
+
|
|
5
|
+
Prerequisites: [Define one validated method](./validation.md)
|
|
6
|
+
|
|
7
|
+
The optional input parser accepts unknown and returns validated arguments, synchronously or asynchronously. A parser object with parse(input) is also supported. Parser failures return a safe Invalid method arguments error without leaking submitted values or schema details. TypeScript types alone do not validate network input. Validation does not replace authentication or ownership checks in the handler/middleware.
|
|
8
|
+
|
|
9
|
+
Related: [Preserve application security](./security.md).
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# Measure successful agent tasks
|
|
2
|
+
|
|
3
|
+
HeliumTS 0.11.0 application reference. Use matching framework and scaffolder versions; see the upgrade notes when migrating from 0.10.2.
|
|
4
|
+
|
|
5
|
+
Prerequisites: None beyond an installed HeliumTS app.
|
|
6
|
+
|
|
7
|
+
HeliumTS reduces explicit client/server wiring. Source length is not total AI cost. Compare successful matched tasks and count input context, output, tool results, retries and failures with fixed models and versions. Do not claim HeliumTS uses fewer tokens than every framework without reproducible evidence.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Mutate and invalidate data
|
|
2
|
+
|
|
3
|
+
HeliumTS 0.11.0 application reference. Use matching framework and scaffolder versions; see the upgrade notes when migrating from 0.10.2.
|
|
4
|
+
|
|
5
|
+
Prerequisites: [Call a validated method from a page](./validation-page.md)
|
|
6
|
+
|
|
7
|
+
useCall(method, options) mutates. call(args) returns the inferred result; onSuccess receives that same type. Failed calls set error state and reject, so catch the promise in event handlers. For ordinary forms, submit(args) returns a handled outcome: { status: "success", data }, { status: "error", error: RpcError }, or { status: "busy" }. It synchronously suppresses another submission while any call from this hook is pending, so the form needs no extra ref lock or rejection catch. isCalling/error still drive the UI. Busy performs no request or callbacks. This is per hook, not cross-component deduplication or server idempotency; call remains concurrent/rejecting. A submission error can also come from a callback after a committed write, so it does not prove rollback. Invalidation starts the existing eventual refresh; submit does not await related reads.
|
|
8
|
+
|
|
9
|
+
Invalidate every related read after success. For a detail edit that changes a title shown in a list, pass both references in `useCall(saveArticle, { invalidate: [getArticle, listArticles] })`. Invalidating only `getArticle` leaves a cached list stale when the user navigates back. Include related filtered lists and summary reads affected by the change. Use the returned result for immediate feedback when needed. Invalidation refetches cached reads.
|
|
10
|
+
|
|
11
|
+
Related: [Read and cache data](./operations.md).
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Read and cache data
|
|
2
|
+
|
|
3
|
+
HeliumTS 0.11.0 application reference. Use matching framework and scaffolder versions; see the upgrade notes when migrating from 0.10.2.
|
|
4
|
+
|
|
5
|
+
Prerequisites: [Call a validated method from a page](./validation-page.md)
|
|
6
|
+
|
|
7
|
+
useFetch(method, args) reads and caches. Required method arguments must be provided. For an argumentless method, useFetch(method) is valid. Use enabled: false to postpone a valid request.
|
|
8
|
+
|
|
9
|
+
Related: [Mutate and invalidate data](./mutations.md), [Consume an HTTP stream](./streaming.md).
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Read and update query parameters
|
|
2
|
+
|
|
3
|
+
HeliumTS 0.11.0 application reference. Use matching framework and scaffolder versions; see the upgrade notes when migrating from 0.10.2.
|
|
4
|
+
|
|
5
|
+
Prerequisites: [Navigate with file routes](./routing.md)
|
|
6
|
+
|
|
7
|
+
Use useRouter().searchParams, a URLSearchParams object. There is no separate useSearchParams export. Clone the current parameters before updating them, then navigate with push or replace; mutating the current object alone does not navigate.
|
|
8
|
+
|
|
9
|
+
```tsx file=src/components/ArticleFilters.tsx
|
|
10
|
+
import { useRouter } from "heliumts/client";
|
|
11
|
+
|
|
12
|
+
export default function ArticleFilters() {
|
|
13
|
+
const router = useRouter();
|
|
14
|
+
const status = router.searchParams.get("status") ?? "all";
|
|
15
|
+
|
|
16
|
+
function showOpen() {
|
|
17
|
+
const next = new URLSearchParams(router.searchParams);
|
|
18
|
+
next.set("status", "open");
|
|
19
|
+
router.replace(`${router.path}?${next.toString()}`, { scrollToTop: false });
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
return <button type="button" onClick={showOpen}>Show open (current: {status})</button>;
|
|
23
|
+
}
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
This preserves unrelated query parameters and replaces the URL without adding a history entry. Validate query values against the app's allowed values before passing them to RPC methods; query strings are untrusted input.
|
|
27
|
+
|
|
28
|
+
Related: [Read and cache data](./operations.md), [Understand input parser behavior](./input-validation.md).
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Choose a rendering mode
|
|
2
|
+
|
|
3
|
+
HeliumTS 0.11.0 application reference. Use matching framework and scaffolder versions; see the upgrade notes when migrating from 0.10.2.
|
|
4
|
+
|
|
5
|
+
Prerequisites: [Keep imports at the right boundary](./imports.md)
|
|
6
|
+
|
|
7
|
+
Pages render on the client unless their file starts with "use ssr" or "use ssg". SSR and SSG adapters expose the same client hook shapes but do not perform browser RPC during rendering. Use the documented server-side props and static props mechanisms for initial data, not a client fetch in server render. A shared adapter does not make browser-only APIs available on the server.
|
|
8
|
+
|
|
9
|
+
Related: [Preserve application security](./security.md).
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Use request context safely
|
|
2
|
+
|
|
3
|
+
HeliumTS 0.11.0 application reference. Use matching framework and scaffolder versions; see the upgrade notes when migrating from 0.10.2.
|
|
4
|
+
|
|
5
|
+
Prerequisites: [Define one validated method](./validation.md)
|
|
6
|
+
|
|
7
|
+
defineMethod handlers receive (args, ctx), where ctx has the public HeliumContext type from heliumts/server. Read request headers from ctx.req.headers, not ctx.headers. Values use Node's IncomingHttpHeaders shape: narrow string, string[] or undefined as appropriate.
|
|
8
|
+
|
|
9
|
+
ctx.req also contains ip, optional url and method, and the raw Node request. In RPC handlers, req.url is the RPC endpoint URL, not the browser page URL; pass page parameters explicitly as validated method arguments. Do not return or log authorization headers, cookies or the whole request.
|
|
10
|
+
|
|
11
|
+
ctx.signal is an AbortSignal for cancellation/disconnect. Pass it to upstream fetch/provider calls and clean up resources in finally. Cancellation only stops work that observes the signal. Middleware-added context fields are unknown until narrowed. For exact fields, read node_modules/heliumts/dist/server/context.d.ts; the public type is HeliumContext, not MethodContext or getRequestContext.
|
|
12
|
+
|
|
13
|
+
Related: [Find installed public API types](./api-reference.md), [Preserve application security](./security.md).
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Navigate with file routes
|
|
2
|
+
|
|
3
|
+
HeliumTS 0.11.0 application reference. Use matching framework and scaffolder versions; see the upgrade notes when migrating from 0.10.2.
|
|
4
|
+
|
|
5
|
+
Prerequisites: [Keep imports at the right boundary](./imports.md)
|
|
6
|
+
|
|
7
|
+
Put pages in src/pages: index.tsx maps to /, articles/index.tsx to /articles, and articles/[id].tsx to /articles/:id. Parenthesized route groups do not appear in the URL. Use Link from heliumts/client for links and useRouter inside the AppRouter tree for navigation and route state.
|
|
8
|
+
|
|
9
|
+
router.params.id holds a dynamic parameter (string or string[]); narrow it before using it as a method argument. router.push(href) adds a history entry, while router.replace(href) replaces the current entry. Use Redirect for declarative redirects rather than navigating during render. For exact signatures, read node_modules/heliumts/dist/client/Router.d.ts.
|
|
10
|
+
|
|
11
|
+
Related: [Read and update query parameters](./query-params.md), [Find installed public API types](./api-reference.md).
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Scaffold a minimal app
|
|
2
|
+
|
|
3
|
+
HeliumTS 0.11.0 application reference. Use matching framework and scaffolder versions; see the upgrade notes when migrating from 0.10.2.
|
|
4
|
+
|
|
5
|
+
Prerequisites: None beyond an installed HeliumTS app.
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm create heliumts-app@latest my-app
|
|
9
|
+
cd my-app
|
|
10
|
+
npm run dev
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
The default starter has one page, one typed RPC method and plain CSS. Pass `--template examples` for the tasks and streaming demo, or `--tailwind` for Tailwind CSS. If you pass `--skip-install`, run `npm install` before starting the dev server.
|
|
14
|
+
|
|
15
|
+
Related: [Verify an application](./verify.md).
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Preserve application security
|
|
2
|
+
|
|
3
|
+
HeliumTS 0.11.0 application reference. Use matching framework and scaffolder versions; see the upgrade notes when migrating from 0.10.2.
|
|
4
|
+
|
|
5
|
+
Prerequisites: None beyond an installed HeliumTS app.
|
|
6
|
+
|
|
7
|
+
Keep rate limits, input-size limits, origin checks, authorization, output escaping and cancellation. Do not send secrets or private user data to the browser. See the focused routing, SSR, SSG, middleware and streaming guides only when the task needs them.
|
|
8
|
+
|
|
9
|
+
Related: [Understand input parser behavior](./input-validation.md), [Choose a rendering mode](./rendering.md).
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Place discoverable server files
|
|
2
|
+
|
|
3
|
+
HeliumTS 0.11.0 application reference. Use matching framework and scaffolder versions; see the upgrade notes when migrating from 0.10.2.
|
|
4
|
+
|
|
5
|
+
Prerequisites: [Keep imports at the right boundary](./imports.md)
|
|
6
|
+
|
|
7
|
+
Put pages under src/pages, methods under src/server and middleware in src/server/_middleware.ts. Start with the explicit exported defineMethod form below; discovery also supports import aliases, typed declarations and relative re-exports within src/server. Arbitrary wrapper factories, computed calls and tsconfig path aliases are not inferred; use an explicit defineMethod export at the discovery boundary.
|
|
8
|
+
|
|
9
|
+
Related: [Define one validated method](./validation.md), [Verify an application](./verify.md).
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Consume an HTTP stream
|
|
2
|
+
|
|
3
|
+
HeliumTS 0.11.0 application reference. Use matching framework and scaffolder versions; see the upgrade notes when migrating from 0.10.2.
|
|
4
|
+
|
|
5
|
+
Prerequisites: [Keep imports at the right boundary](./imports.md), [Place discoverable server files](./server-files.md)
|
|
6
|
+
|
|
7
|
+
useStreaming(method) consumes an AsyncIterable method over HTTP with length-prefixed MessagePack frames. Unary hooks reject streaming methods at compile time. Keep cancellation and server abort handling intact.
|
|
8
|
+
|
|
9
|
+
Related: [Choose an explicit HTTP endpoint](./http-handlers.md), [Preserve application security](./security.md).
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Call a validated method from a page
|
|
2
|
+
|
|
3
|
+
HeliumTS 0.11.0 application reference. Use matching framework and scaffolder versions; see the upgrade notes when migrating from 0.10.2.
|
|
4
|
+
|
|
5
|
+
Prerequisites: [Define one validated method](./validation.md), [Keep imports at the right boundary](./imports.md)
|
|
6
|
+
|
|
7
|
+
This page uses the `greet` method from the validated-method guide. Define it first, then run `npx helium typegen` if the development server is stopped.
|
|
8
|
+
|
|
9
|
+
```tsx file=src/pages/index.tsx
|
|
10
|
+
import { useFetch } from "heliumts/client";
|
|
11
|
+
import { greet } from "../rpc.generated";
|
|
12
|
+
|
|
13
|
+
export default function Home() {
|
|
14
|
+
const { data, isLoading, error } = useFetch(greet, { name: "Helium" });
|
|
15
|
+
if (isLoading) return <p>Loading...</p>;
|
|
16
|
+
if (error) return <p role="alert">{error}</p>;
|
|
17
|
+
return <h1>{data?.message}</h1>;
|
|
18
|
+
}
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Related: [Read and cache data](./operations.md).
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Define one validated method
|
|
2
|
+
|
|
3
|
+
HeliumTS 0.11.0 application reference. Use matching framework and scaffolder versions; see the upgrade notes when migrating from 0.10.2.
|
|
4
|
+
|
|
5
|
+
Prerequisites: [Keep imports at the right boundary](./imports.md), [Place discoverable server files](./server-files.md)
|
|
6
|
+
|
|
7
|
+
In the framework repository, npm run test:docs compiles these two examples together and tests the extracted server example with valid and malformed inputs.
|
|
8
|
+
|
|
9
|
+
```ts file=src/server/greeting.ts
|
|
10
|
+
import { defineMethod } from "heliumts/server";
|
|
11
|
+
|
|
12
|
+
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
13
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
export const greet = defineMethod(
|
|
17
|
+
({ name }: { name: string }) => ({ message: `Hello ${name}` }),
|
|
18
|
+
{
|
|
19
|
+
input(value: unknown) {
|
|
20
|
+
if (!isRecord(value) || typeof value.name !== "string") {
|
|
21
|
+
throw new Error("Expected a name");
|
|
22
|
+
}
|
|
23
|
+
const name = value.name.trim();
|
|
24
|
+
if (!name || name.length > 80) throw new Error("Invalid name");
|
|
25
|
+
return { name };
|
|
26
|
+
},
|
|
27
|
+
}
|
|
28
|
+
);
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Start with unknown, narrow to a record, then validate each field before using it. Keep the handler argument type explicit so the parser return and client arguments agree; return the transformed object rather than asserting a type with a cast.
|
|
32
|
+
|
|
33
|
+
Related: [Understand input parser behavior](./input-validation.md), [Call a validated method from a page](./validation-page.md).
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Verify an application
|
|
2
|
+
|
|
3
|
+
HeliumTS 0.11.0 application reference. Use matching framework and scaffolder versions; see the upgrade notes when migrating from 0.10.2.
|
|
4
|
+
|
|
5
|
+
Prerequisites: [Scaffold a minimal app](./scaffold.md)
|
|
6
|
+
|
|
7
|
+
In a new starter, run the single verification script:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm run verify
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
It runs `check`, `lint`, then `build` once each and stops on the first failure. Fix that failure and rerun verify. Check generates `src/rpc.generated.ts`, validates discovery and checks every referenced TypeScript project. A separate typegen or typecheck invocation is unnecessary in this sequence. Keep runtime tests required by your task; production build and type checks do not replace them.
|
|
14
|
+
|
|
15
|
+
For an existing app without verify, run its supplied check, lint and production-build scripts. `helium check` itself remains generation plus TypeScript: it does not run app scripts. `helium typegen` is available for generation alone; dev and build also keep RPC references current. Treat the RPC module as generated output.
|
|
16
|
+
|
|
17
|
+
Use inspect/api only to answer a specific discovery question, before verification when needed; they are not extra verification stages.
|
|
18
|
+
|
|
19
|
+
Related: [Place discoverable server files](./server-files.md).
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Orient in an installed app
|
|
2
|
+
|
|
3
|
+
HeliumTS 0.11.0 application reference. Use matching framework and scaffolder versions; see the upgrade notes when migrating from 0.10.2.
|
|
4
|
+
|
|
5
|
+
Prerequisites: None beyond an installed HeliumTS app.
|
|
6
|
+
|
|
7
|
+
Read the app's AGENTS.md first. For a known app method or route, use `npx helium inspect --rpc name --json` or `--route '/posts/:id' --json`. For an exact framework signature, use `npx helium api useCall --from client --json` or `npx helium api defineMethod --from server --json`. Discover unknown API names with `npx helium api --list --match fragment`.
|
|
8
|
+
|
|
9
|
+
Open one focused topic from node_modules/heliumts/docs/agent/index.md when you need a concept or example. Follow prerequisite links only to fill a gap; the full reference at node_modules/heliumts/docs/agent-guide.md is available for broader context.
|
|
10
|
+
|
|
11
|
+
Related: [Scaffold a minimal app](./scaffold.md), [Verify an application](./verify.md).
|