feat(metadata): type check passing metadata to actions

If a metadata schema is provided via `defineMetadataSchema` init function, and the `metadata` method
is not used before `action`/`stateAction` method, now an error will inform the user that the type is
incomplete.

Author: TheEdoRan

packages/next-safe-action/src/action-builder.ts

@@ -42,7 +42,7 @@ export function actionBuilder<
 	OS extends StandardSchemaV1 | undefined = undefined, // output schema
 	const BAS extends readonly StandardSchemaV1[] = [],
 	CVE = undefined,
->(args: SafeActionClientArgs<ServerError, ODVES, MetadataSchema, MD, Ctx, ISF, IS, OS, BAS, CVE>) {
+>(args: SafeActionClientArgs<ServerError, ODVES, MetadataSchema, MD, true, Ctx, ISF, IS, OS, BAS, CVE>) {
 	const bindArgsSchemas = args.bindArgsSchemas ?? [];
 
 	function buildAction({ withState }: { withState: false }): {

packages/next-safe-action/src/index.types.ts

@@ -38,6 +38,7 @@ export type SafeActionClientArgs<
 	ODVES extends DVES | undefined, // override default validation errors shape
 	MetadataSchema extends StandardSchemaV1 | undefined = undefined,
 	MD = InferOutputOrDefault<MetadataSchema, undefined>, // metadata type (inferred from metadata schema)
+	MDProvided extends boolean = MetadataSchema extends undefined ? true : false,
 	Ctx extends object = {},
 	ISF extends (() => Promise<StandardSchemaV1>) | undefined = undefined, // input schema function
 	IS extends StandardSchemaV1 | undefined = ISF extends Function ? Awaited<ReturnType<ISF>> : undefined, // input schema
@@ -48,6 +49,7 @@ export type SafeActionClientArgs<
 	middlewareFns: MiddlewareFn<ServerError, any, any, any>[];
 	metadataSchema: MetadataSchema;
 	metadata: MD;
+	metadataProvided?: MDProvided;
 	inputSchemaFn: ISF;
 	outputSchema: OS;
 	bindArgsSchemas: BAS;
@@ -295,7 +297,7 @@ export type InferMiddlewareFnNextCtx<T> =
  * Infer the context type of a safe action client or middleware function.
  */
 export type InferCtx<T> = T extends
-	| SafeActionClient<any, any, any, any, infer Ctx extends object, any, any, any, any, any>
+	| SafeActionClient<any, any, any, any, false, infer Ctx extends object, any, any, any, any, any>
 	| MiddlewareFn<any, any, infer Ctx extends object, any>
 	? Ctx
 	: never;
@@ -304,7 +306,7 @@ export type InferCtx<T> = T extends
  * Infer the metadata type of a safe action client or middleware function.
  */
 export type InferMetadata<T> = T extends
-	| SafeActionClient<any, any, any, infer MD, any, any, any, any, any, any>
+	| SafeActionClient<any, any, any, infer MD, false, any, any, any, any, any, any>
 	| MiddlewareFn<any, infer MD, any, any>
 	? MD
 	: never;
@@ -313,7 +315,7 @@ export type InferMetadata<T> = T extends
  * Infer the server error type from a safe action client or a middleware function or a safe action function.
  */
 export type InferServerError<T> = T extends
-	| SafeActionClient<infer ServerError, any, any, any, any, any, any, any, any, any>
+	| SafeActionClient<infer ServerError, any, any, any, any, any, any, any, any, any, any>
 	| MiddlewareFn<infer ServerError, any, any, any>
 	| SafeActionFn<infer ServerError, any, any, any, any>
 	| SafeStateActionFn<infer ServerError, any, any, any, any>

packages/next-safe-action/src/safe-action-client.ts

@@ -19,16 +19,19 @@ export class SafeActionClient<
 	ODVES extends DVES | undefined, // override default validation errors shape
 	MetadataSchema extends StandardSchemaV1 | undefined = undefined,
 	MD = InferOutputOrDefault<MetadataSchema, undefined>, // metadata type (inferred from metadata schema)
+	MDProvided extends boolean = MetadataSchema extends undefined ? true : false,
 	Ctx extends object = {},
 	ISF extends (() => Promise<StandardSchemaV1>) | undefined = undefined, // input schema function
 	IS extends StandardSchemaV1 | undefined = ISF extends Function ? Awaited<ReturnType<ISF>> : undefined, // input schema
 	OS extends StandardSchemaV1 | undefined = undefined, // output schema
 	const BAS extends readonly StandardSchemaV1[] = [],
 	CVE = undefined,
 > {
-	readonly #args: SafeActionClientArgs<ServerError, ODVES, MetadataSchema, MD, Ctx, ISF, IS, OS, BAS, CVE>;
+	readonly #args: SafeActionClientArgs<ServerError, ODVES, MetadataSchema, MD, MDProvided, Ctx, ISF, IS, OS, BAS, CVE>;
 
-	constructor(args: SafeActionClientArgs<ServerError, ODVES, MetadataSchema, MD, Ctx, ISF, IS, OS, BAS, CVE>) {
+	constructor(
+		args: SafeActionClientArgs<ServerError, ODVES, MetadataSchema, MD, MDProvided, Ctx, ISF, IS, OS, BAS, CVE>
+	) {
 		this.#args = args;
 	}
 
@@ -56,6 +59,7 @@ export class SafeActionClient<
 		return new SafeActionClient({
 			...this.#args,
 			metadata: data,
+			metadataProvided: true,
 		});
 	}
 
@@ -141,6 +145,9 @@ export class SafeActionClient<
 	 * {@link https://next-safe-action.dev/docs/define-actions/instance-methods#action--stateaction See docs for more information}
 	 */
 	action<Data extends InferOutputOrDefault<OS, any>>(
+		this: MDProvided extends true
+			? SafeActionClient<ServerError, ODVES, MetadataSchema, MD, MDProvided, Ctx, ISF, IS, OS, BAS, CVE>
+			: never,
 		serverCodeFn: ServerCodeFn<MD, Ctx, IS, BAS, Data>,
 		utils?: SafeActionUtils<ServerError, MD, Ctx, IS, BAS, CVE, Data>
 	) {
@@ -156,6 +163,9 @@ export class SafeActionClient<
 	 * {@link https://next-safe-action.dev/docs/define-actions/instance-methods#action--stateaction See docs for more information}
 	 */
 	stateAction<Data extends InferOutputOrDefault<OS, any>>(
+		this: MDProvided extends true
+			? SafeActionClient<ServerError, ODVES, MetadataSchema, MD, MDProvided, Ctx, ISF, IS, OS, BAS, CVE>
+			: never,
 		serverCodeFn: StateServerCodeFn<ServerError, MD, Ctx, IS, BAS, CVE, Data>,
 		utils?: SafeActionUtils<ServerError, MD, Ctx, IS, BAS, CVE, Data>
 	) {