@stacksjs/actions 0.72.55 → 0.72.57

package/dist/action.d.ts

@@ -33,7 +33,7 @@ export declare interface ActionResponse {
   description: string
   schema?: Record<string, unknown>
 }
-declare interface ActionOptions<TModel = string, TValidations extends ActionValidations | undefined = undefined, TPath extends string = '', /** * The payload `handle` receives when the action is invoked by something * other than the router - an event listener, for instance, which calls it * with the event object rather than a request (`app/Events.ts` maps * 'user:registered' straight onto an action name). Defaults to `never`, * which leaves every HTTP action typed exactly as before. */ TPayload = never,> {
+declare interface ActionOptions<TModel = string, TValidations extends ActionValidations | undefined = undefined, TPath extends string = '', /** * The payload `handle` receives when the action is invoked by something * other than the router - an event listener, for instance, which calls it * with the event object rather than a request (`app/Events.ts` maps * 'user:registered' straight onto an action name). Defaults to `never`, * which leaves every HTTP action typed exactly as before. */ TPayload = never, /** * What `handle` answers with, inferred from the handler body. * * `handle` used to be declared as returning the whole {@link ActionResult} * union, which is a complete description of what the router will accept and * a useless one for anybody downstream: the concrete shape an action * actually returns was erased the moment it was written down. A typed client * asking "what comes back from this endpoint" got the union back and could * say nothing more. * * Inferred, so nothing has to be annotated, and constrained to * {@link ActionResult} so the router's contract is unchanged. Defaults to * the full union, which is what an action whose return type cannot be * inferred falls back to - the behaviour every action had before. */ TResult extends ActionResult = ActionResult,> {
   name?: string
   description?: string
   apiResponse?: boolean
@@ -60,7 +60,7 @@ declare interface ActionOptions<TModel = string, TValidations extends ActionVali
   handle: {
     bivarianceHack: (
       request: [TPayload] extends [never] ? InferRequest<TModel, TValidations, TPath> : TPayload,
-    ) => ActionResult | Promise<ActionResult>
+    ) => TResult | Promise<TResult>
   }['bivarianceHack']
   dependencies?: () => Record<string, unknown>
 }
@@ -115,7 +115,7 @@ export type ActionResult = | Response
   | boolean
   | object
   | unknown[];
-export declare class Action<TModel = string, TValidations extends ActionValidations | undefined = undefined, TPath extends string = '', TPayload = never,> {
+export declare class Action<TModel = string, TValidations extends ActionValidations | undefined = undefined, TPath extends string = '', TPayload = never, /** @see {@link ActionOptions} - inferred from `handle`'s return type. */ TResult extends ActionResult = ActionResult,> {
   name?: string;
   description?: string;
   apiResponse?: boolean;
@@ -134,7 +134,7 @@ export declare class Action<TModel = string, TValidations extends ActionValidati
   csrf?: boolean;
   authorize?: ActionOptions<TModel, TValidations, TPath>['authorize'];
   before?: ActionOptions<TModel, TValidations, TPath>['before'];
-  handle: ActionOptions<TModel, TValidations, TPath, TPayload>['handle'];
+  handle: ActionOptions<TModel, TValidations, TPath, TPayload, TResult>['handle'];
   model?: string;
   modelDefinition?: TModel;
   constructor({
@@ -159,7 +159,7 @@ export declare class Action<TModel = string, TValidations extends ActionValidati
   authorize,
   before,
   dependencies,
-}: ActionOptions<TModel, TValidations, TPath, TPayload>);
+}: ActionOptions<TModel, TValidations, TPath, TPayload, TResult>);
   get deps(): Record<string, unknown>;
   overrideDependencies(overrides: Record<string, unknown>): void;
   resetDependencies(): void;

package/dist/generate/action-types.d.ts

@@ -1 +1,9 @@
-export {};
+/**
+ * Write `storage/framework/types/actions.d.ts`.
+ *
+ * Controllers stay a pattern rather than a union: they are addressed as
+ * `'Controllers/UserController@show'`, and the method half is a member name
+ * that would need the file parsed rather than listed. Catching the shape is
+ * what was already on offer for them, and it is unchanged.
+ */
+export declare function generateActionTypes(): Promise<void>;

package/dist/generate/action-types.js

@@ -1,7 +1,46 @@
-import{readdir}from"node:fs/promises";import{log}from"@stacksjs/logging";import{path as p}from"@stacksjs/path";import{storage}from"@stacksjs/storage";log.info("Generating action types...");const domain="Actions",files=await readdir(p.appPath(domain),{recursive:!0}),validActions=`// This file is auto-generated by Stacks. Do not edit this file manually.
+import{existsSync}from"node:fs";import{readdir}from"node:fs/promises";import{log}from"@stacksjs/logging";import{path as p}from"@stacksjs/path";import{storage}from"@stacksjs/storage";function actionDirectories(){const candidates=[p.appPath("Actions"),p.storagePath("framework/defaults/app/Actions")];try{const pkgJson=Bun.resolveSync("@stacksjs/defaults/package.json",process.cwd());candidates.push(`${pkgJson.slice(0,pkgJson.lastIndexOf("/"))}/app/Actions`)}catch{}return candidates.filter((dir)=>existsSync(dir))}async function collectActionPaths(){const found=new Set;for(const dir of actionDirectories()){const files=await readdir(dir,{recursive:!0});for(const file of files){if(!file.endsWith(".ts")||file.endsWith(".d.ts"))continue;found.add(`Actions/${file.slice(0,-3)}`)}}return[...found].sort()}async function collectMiddlewareAliases(){const found=new Set,candidates=[p.appPath("Middleware.ts"),p.storagePath("framework/defaults/app/Middleware.ts")];for(const file of candidates){if(!existsSync(file))continue;try{const module=await import(`${file}?t=${Date.now()}`);for(const alias of Object.keys(module.default??{}))found.add(alias)}catch{}}return[...found].sort()}async function collectNamedRoutes(){const registryFile=p.appPath("Routes.ts");if(!existsSync(registryFile))return{};try{const{listNamedRoutes,loadRoutes}=await import("@stacksjs/router"),{default:routeRegistry}=await import(registryFile);await loadRoutes(routeRegistry);return listNamedRoutes()}catch(error){log.debug("[generate:types] Could not load routes for named-route types",{error});return{}}}export async function generateActionTypes(){log.info("Generating action types...");const actions=await collectActionPaths();if(actions.length===0){log.debug("[generate:types] No action directories found; leaving actions.d.ts alone");return}const aliases=await collectMiddlewareAliases(),namedRoutes=await collectNamedRoutes(),union=actions.map((action)=>`
+  | '${action}'`).join(""),middlewareUnion=aliases.flatMap((alias)=>[`
+  | '${alias}'`,`
+  | '!${alias}'`]).join(""),routeEntries=Object.entries(namedRoutes).sort(([left],[right])=>left.localeCompare(right)).map(([name,routePath])=>`
+  '${name}': '${routePath}'`).join(""),contents=`// This file is auto-generated by Stacks. Do not edit this file manually.
 // If you wish to rename an action, please do so by editing the file name.
 //
 // For more information, please visit: https://stacksjs.com/docs
 
-export type ActionPath = ${files.filter((file)=>file.endsWith(".ts")).map((value)=>`'${domain}/${value.replace(".ts","")}'`).join(" | ")}
-`;await storage.writeFile(p.frameworkPath("types/actions.d.ts"),validActions);
+/**
+ * Every action this application can route to: its own, plus the framework
+ * defaults it has not overridden.
+ */
+export type ActionPath =${union}
+
+/**
+ * Every middleware alias this application registers, and its negated form.
+ */
+export type MiddlewareAlias =${middlewareUnion||`
+  | string`}
+
+/**
+ * Every named route, and the path it resolves to.
+ *
+ * A type alias, NOT an interface: only aliases of object literals get an
+ * implicit index signature, so an interface here fails the router's
+ * \`extends Record<string, string>\` shape check and the whole map is quietly
+ * ignored.
+ */
+export type NamedRoutes = {${routeEntries?`${routeEntries}
+`:""}}
+
+/**
+ * Handed to the router, so \`route.get(path, 'Actions/\u2026')\` and
+ * \`.middleware('auth')\` are checked against the lists above rather than
+ * against a string. A controller reference stays a pattern - the method half is
+ * a member name, not a filename.
+ */
+declare module '@stacksjs/bun-router' {
+  interface RouterTypeRegistry {
+    actions: ActionPath | \`\${string}Controller@\${string}\`
+    middleware: MiddlewareAlias
+    routes: NamedRoutes
+  }
+}
+`;await storage.writeFile(p.frameworkPath("types/actions.d.ts"),contents);log.debug(`[generate:types] Wrote ${actions.length} action paths, ${aliases.length} middleware aliases and ${Object.keys(namedRoutes).length} named routes`)}

package/dist/generate/index.js

@@ -1 +1 @@
-import*as fs from"node:fs";import process from"node:process";import{runCommand}from"@stacksjs/cli";import{Action,NpmScript}from"@stacksjs/enums";import{log}from"@stacksjs/logging";import{frameworkPath,projectPath,storagePath}from"@stacksjs/path";import{ExitCode}from"@stacksjs/types";import{runNpmScript}from"@stacksjs/utils";import{runAction}from"../helpers";import{generateVsCodeCustomData as genVsCodeCustomData}from"../helpers/vscode-custom-data";import{generateProjectImages}from"./images";import{generateEnvFiles}from"./env-files";export{generateProjectImages}from"./images";export{generateVSchema}from"./vschema";export async function invoke(options){if(options?.types)await generateTypes(options);else if(options?.entries)await generateLibEntries(options);else if(options?.webTypes)await generateWebTypes(options);else if(options?.customData)await generateVsCodeCustomData();else if(options?.ideHelpers)await generateIdeHelpers(options);else if(options?.componentMeta)await generateComponentMeta();else if(options?.coreSymlink)await generateCoreSymlink();else if(options?.openApiSpec)await generateOpenApiSpec();else if(options?.images)await generateProjectImages({verbose:options?.verbose})}export function generate(options){return invoke(options)}export async function generateLibEntries(options){const result=await runAction(Action.GenerateLibraryEntries,{...options,cwd:projectPath()});if(result.isErr){log.error("There was an error generating your library entry points",result.error);process.exit(ExitCode.FatalError)}log.success("Library entry points generated successfully")}export async function generateWebTypes(options){const result=await runNpmScript(NpmScript.GenerateWebTypes,options);if(result.isErr){log.error("There was an error generating the web-types.json file.",result.error);process.exit(ExitCode.FatalError)}log.success("Successfully generated the web-types.json file")}export async function generateVsCodeCustomData(){const result=await genVsCodeCustomData();if(result.isErr){log.error("There was an error generating the custom-elements.json file.",result.error);process.exit(ExitCode.FatalError)}await runAction(Action.LintFix,{verbose:!0,cwd:projectPath()});log.success("Successfully generated the custom-elements.json file")}export async function generateIdeHelpers(options){const result=await runNpmScript(NpmScript.GenerateIdeHelpers,options);if(result.isErr){log.error("There was an error generating IDE helpers.",result.error);process.exit(ExitCode.FatalError)}await runAction(Action.LintFix,{verbose:!0,cwd:projectPath()});log.success("Successfully generated IDE helpers")}export async function generateComponentMeta(){const result=await genVsCodeCustomData();if(result.isErr){log.error("There was an error generating your component meta information.",result.error);process.exit(ExitCode.FatalError)}await runAction(Action.LintFix,{verbose:!0,cwd:projectPath()});log.success("Successfully generated component meta information")}export async function generateTypes(options){await generateEnvFiles();const entry=frameworkPath("core/actions/src/generate/types.ts");if(!fs.existsSync(entry)){await import(`./types?t=${Date.now()}`);return}const result=await runNpmScript(NpmScript.GenerateTypes,{cwd:frameworkPath(),...options});if(result.isErr){log.error("There was an error generating your types.",result.error);throw result.error instanceof Error?result.error:Error(String(result.error))}log.success("Types were generated successfully")}export async function watchTypes(options){try{const manifestPath=`${frameworkPath()}/package.json`,text=fs.existsSync(manifestPath)?fs.readFileSync(manifestPath,"utf-8"):"";if(!(text?JSON.parse(text):{})?.scripts?.["generate:types"]){log.warn("[generate:types --watch] no `generate:types` script in framework package.json - type regeneration disabled. dev:api will keep running, but type definitions won't auto-refresh on model/config changes.");return}}catch{}const watched=[projectPath("app/Models"),storagePath("framework/defaults/app/Models"),projectPath("config"),projectPath("database/migrations")];log.info(`[generate:types --watch] watching ${watched.length} directories`);let pending=null,inflight=!1;const trigger=()=>{if(pending)clearTimeout(pending);pending=setTimeout(async()=>{if(inflight)return;inflight=!0;try{log.info("[generate:types --watch] change detected, regenerating\u2026");await generateTypes(options);log.success("[generate:types --watch] types up to date")}catch(err){log.error("[generate:types --watch] regeneration failed:",err)}finally{inflight=!1}},200)},watchers=[];for(const dir of watched)try{if(!fs.existsSync(dir))continue;const w=fs.watch(dir,{recursive:!0},()=>trigger());watchers.push(w)}catch(err){log.warn(`[generate:types --watch] cannot watch ${dir}: ${err}`)}if(watchers.length===0){log.warn("[generate:types --watch] no directories to watch - exiting");return}await new Promise((resolve)=>{process.once("SIGINT",()=>{log.info("[generate:types --watch] stopping");for(const w of watchers)try{w.close()}catch{}resolve()})})}export function generatePantryConfig(){log.success("Successfully generated `./pantry.yaml` based on your config")}export async function generateSeeder(){}export async function generateCoreSymlink(){const link=projectPath(".framework");if(fs.existsSync(link))await runCommand(`rm -f ${link}`);await runCommand(`ln -s ${frameworkPath()} ${link}`)}export async function generateOpenApiSpec(){const{generateOpenApi}=await import("@stacksjs/api");await generateOpenApi();log.success("Successfully generated Open API Spec")}
+import*as fs from"node:fs";import process from"node:process";import{runCommand}from"@stacksjs/cli";import{Action,NpmScript}from"@stacksjs/enums";import{log}from"@stacksjs/logging";import{frameworkPath,projectPath,storagePath}from"@stacksjs/path";import{ExitCode}from"@stacksjs/types";import{runNpmScript}from"@stacksjs/utils";import{runAction}from"../helpers";import{generateVsCodeCustomData as genVsCodeCustomData}from"../helpers/vscode-custom-data";import{generateProjectImages}from"./images";import{generateActionTypes}from"./action-types";import{generateEnvFiles}from"./env-files";export{generateProjectImages}from"./images";export{generateVSchema}from"./vschema";export async function invoke(options){if(options?.types)await generateTypes(options);else if(options?.entries)await generateLibEntries(options);else if(options?.webTypes)await generateWebTypes(options);else if(options?.customData)await generateVsCodeCustomData();else if(options?.ideHelpers)await generateIdeHelpers(options);else if(options?.componentMeta)await generateComponentMeta();else if(options?.coreSymlink)await generateCoreSymlink();else if(options?.openApiSpec)await generateOpenApiSpec();else if(options?.images)await generateProjectImages({verbose:options?.verbose})}export function generate(options){return invoke(options)}export async function generateLibEntries(options){const result=await runAction(Action.GenerateLibraryEntries,{...options,cwd:projectPath()});if(result.isErr){log.error("There was an error generating your library entry points",result.error);process.exit(ExitCode.FatalError)}log.success("Library entry points generated successfully")}export async function generateWebTypes(options){const result=await runNpmScript(NpmScript.GenerateWebTypes,options);if(result.isErr){log.error("There was an error generating the web-types.json file.",result.error);process.exit(ExitCode.FatalError)}log.success("Successfully generated the web-types.json file")}export async function generateVsCodeCustomData(){const result=await genVsCodeCustomData();if(result.isErr){log.error("There was an error generating the custom-elements.json file.",result.error);process.exit(ExitCode.FatalError)}await runAction(Action.LintFix,{verbose:!0,cwd:projectPath()});log.success("Successfully generated the custom-elements.json file")}export async function generateIdeHelpers(options){const result=await runNpmScript(NpmScript.GenerateIdeHelpers,options);if(result.isErr){log.error("There was an error generating IDE helpers.",result.error);process.exit(ExitCode.FatalError)}await runAction(Action.LintFix,{verbose:!0,cwd:projectPath()});log.success("Successfully generated IDE helpers")}export async function generateComponentMeta(){const result=await genVsCodeCustomData();if(result.isErr){log.error("There was an error generating your component meta information.",result.error);process.exit(ExitCode.FatalError)}await runAction(Action.LintFix,{verbose:!0,cwd:projectPath()});log.success("Successfully generated component meta information")}export async function generateTypes(options){await generateEnvFiles();await generateActionTypes();const entry=frameworkPath("core/actions/src/generate/types.ts");if(!fs.existsSync(entry)){await import(`./types?t=${Date.now()}`);return}const result=await runNpmScript(NpmScript.GenerateTypes,{cwd:frameworkPath(),...options});if(result.isErr){log.error("There was an error generating your types.",result.error);throw result.error instanceof Error?result.error:Error(String(result.error))}log.success("Types were generated successfully")}export async function watchTypes(options){try{const manifestPath=`${frameworkPath()}/package.json`,text=fs.existsSync(manifestPath)?fs.readFileSync(manifestPath,"utf-8"):"";if(!(text?JSON.parse(text):{})?.scripts?.["generate:types"]){log.warn("[generate:types --watch] no `generate:types` script in framework package.json - type regeneration disabled. dev:api will keep running, but type definitions won't auto-refresh on model/config changes.");return}}catch{}const watched=[projectPath("app/Models"),storagePath("framework/defaults/app/Models"),projectPath("config"),projectPath("database/migrations")];log.info(`[generate:types --watch] watching ${watched.length} directories`);let pending=null,inflight=!1;const trigger=()=>{if(pending)clearTimeout(pending);pending=setTimeout(async()=>{if(inflight)return;inflight=!0;try{log.info("[generate:types --watch] change detected, regenerating\u2026");await generateTypes(options);log.success("[generate:types --watch] types up to date")}catch(err){log.error("[generate:types --watch] regeneration failed:",err)}finally{inflight=!1}},200)},watchers=[];for(const dir of watched)try{if(!fs.existsSync(dir))continue;const w=fs.watch(dir,{recursive:!0},()=>trigger());watchers.push(w)}catch(err){log.warn(`[generate:types --watch] cannot watch ${dir}: ${err}`)}if(watchers.length===0){log.warn("[generate:types --watch] no directories to watch - exiting");return}await new Promise((resolve)=>{process.once("SIGINT",()=>{log.info("[generate:types --watch] stopping");for(const w of watchers)try{w.close()}catch{}resolve()})})}export function generatePantryConfig(){log.success("Successfully generated `./pantry.yaml` based on your config")}export async function generateSeeder(){}export async function generateCoreSymlink(){const link=projectPath(".framework");if(fs.existsSync(link))await runCommand(`rm -f ${link}`);await runCommand(`ln -s ${frameworkPath()} ${link}`)}export async function generateOpenApiSpec(){const{generateOpenApi}=await import("@stacksjs/api");await generateOpenApi();log.success("Successfully generated Open API Spec")}

package/dist/scaffold-crud.js

@@ -83,4 +83,4 @@ ${migrationColumns(fields)}
 `);log.info(`[dry-run] would write ${path} (${lines.length} lines)`);process.stdout.write(`${lines.slice(0,60).map((l)=>`  ${l}`).join(`
 `)}
 
-`);return}await writeTextFile({path,data:contents})}export async function scaffoldCrud(name,options){const Model=pascalCase(name);if(!Model)throw Error("scaffold:crud requires a non-empty resource name");const fields=parseFields(options.fields);log.info(`Scaffolding CRUD for ${italic(Model)} (${fields.length||"no"} fields)`);await writeFile(p.userModelsPath(`${Model}.ts`),modelStub(Model,fields));const migrationName=`${Date.now().toString()}-create-${pluralize(snakeCase(name))}-table.ts`;await writeFile(p.userMigrationsPath(migrationName),migrationStub(name,fields));for(const kind of["Index","Show","Store","Update","Destroy"])await writeFile(p.userActionsPath(`${Model}${kind}Action.ts`),actionStub(name,kind,fields));log.success(`CRUD scaffold complete: model + migration + 5 actions for ${Model}`);log.info(`Next: register \`route.resource('${pluralize(snakeCase(name))}', '${Model}')\` in routes/api.ts`)}
+`);return}await writeTextFile({path,data:contents})}export async function scaffoldCrud(name,options){const Model=pascalCase(name);if(!Model)throw Error("scaffold:crud requires a non-empty resource name");const fields=parseFields(options.fields);log.info(`Scaffolding CRUD for ${italic(Model)} (${fields.length||"no"} fields)`);await writeFile(p.userModelsPath(`${Model}.ts`),modelStub(Model,fields));const migrationName=`${Date.now().toString()}-create-${pluralize(snakeCase(name))}-table.ts`;await writeFile(p.userMigrationsPath(migrationName),migrationStub(name,fields));for(const kind of["Index","Show","Store","Update","Destroy"])await writeFile(p.userActionsPath(`${Model}${kind}Action.ts`),actionStub(name,kind,fields));log.success(`CRUD scaffold complete: model + migration + 5 actions for ${Model}`);log.info(`Next: run \`buddy generate:types\`, then register \`route.resource('${pluralize(snakeCase(name))}', '${Model}')\` in routes/api.ts`)}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/actions",
   "type": "module",
   "sideEffects": false,
-  "version": "0.72.55",
+  "version": "0.72.57",
   "description": "The Stacks actions.",
   "author": "Chris Breuer",
   "contributors": [
@@ -59,35 +59,35 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/config": "0.72.55",
+    "@stacksjs/config": "0.72.57",
     "@stacksjs/bumpx": "^0.2.6",
     "@stacksjs/bunpress": "^0.2.8",
     "@stacksjs/logsmith": "^0.2.3",
-    "@stacksjs/registry": "0.72.55",
+    "@stacksjs/registry": "0.72.57",
     "@stacksjs/stx": "^0.2.219",
     "@stacksjs/ts-cloud": "^0.11.4",
     "@stacksjs/ts-md": "^0.1.1"
   },
   "devDependencies": {
-    "@stacksjs/api": "0.72.55",
-    "@stacksjs/cli": "0.72.55",
-    "@stacksjs/database": "0.72.55",
+    "@stacksjs/api": "0.72.57",
+    "@stacksjs/cli": "0.72.57",
+    "@stacksjs/database": "0.72.57",
     "@stacksjs/tlsx": "^0.13.2",
     "better-dx": "^0.2.24",
-    "@stacksjs/dns": "0.72.55",
-    "@stacksjs/enums": "0.72.55",
-    "@stacksjs/env": "0.72.55",
-    "@stacksjs/error-handling": "0.72.55",
-    "@stacksjs/image": "0.72.55",
-    "@stacksjs/logging": "0.72.55",
-    "@stacksjs/path": "0.72.55",
-    "@stacksjs/security": "0.72.55",
-    "@stacksjs/cms": "0.72.55",
-    "@stacksjs/sites": "0.72.55",
-    "@stacksjs/storage": "0.72.55",
-    "@stacksjs/strings": "0.72.55",
-    "@stacksjs/utils": "0.72.55",
-    "@stacksjs/validation": "0.72.55"
+    "@stacksjs/dns": "0.72.57",
+    "@stacksjs/enums": "0.72.57",
+    "@stacksjs/env": "0.72.57",
+    "@stacksjs/error-handling": "0.72.57",
+    "@stacksjs/image": "0.72.57",
+    "@stacksjs/logging": "0.72.57",
+    "@stacksjs/path": "0.72.57",
+    "@stacksjs/security": "0.72.57",
+    "@stacksjs/cms": "0.72.57",
+    "@stacksjs/sites": "0.72.57",
+    "@stacksjs/storage": "0.72.57",
+    "@stacksjs/strings": "0.72.57",
+    "@stacksjs/utils": "0.72.57",
+    "@stacksjs/validation": "0.72.57"
   },
   "peerDependencies": {
     "pickier": "^0.1.58",