@gencow/core 0.1.7 → 0.1.8

package/dist/reactive.d.ts

@@ -153,13 +153,43 @@ export declare function query<TSchema = any, TReturn = any>(key: string, handler
     public?: boolean;
     handler: QueryHandler<InferArgs<TSchema>, TReturn>;
 }): QueryDef<TSchema, TReturn>;
-export declare function mutation<TSchema = any, TReturn = any>(invalidatesOrDef: string[] | {
+/**
+ * mutation — 데이터 변경 함수를 선언적으로 등록합니다.
+ *
+ * 3가지 호출 방식 지원 (query와 동일한 패턴 우선):
+ *
+ * @example
+ * ```typescript
+ * // ✅ 권장: query와 동일한 (name, def) 패턴
+ * mutation("tasks.create", {
+ *     invalidates: [],
+ *     args: { title: v.string() },
+ *     handler: async (ctx, args) => { ... },
+ * });
+ *
+ * // ✅ 객체 스타일 (하위 호환)
+ * mutation({
+ *     name: "tasks.create",
+ *     invalidates: [],
+ *     handler: async (ctx) => { ... },
+ * });
+ *
+ * // ⚠️ Legacy 배열 스타일 (비권장)
+ * mutation(["tasks.list"], handler, "tasks.create");
+ * ```
+ */
+export declare function mutation<TSchema = any, TReturn = any>(nameOrInvalidatesOrDef: string | string[] | {
     name?: string;
     args?: TSchema;
     public?: boolean;
     invalidates: string[];
     handler: MutationHandler<InferArgs<TSchema>, TReturn>;
-}, handler?: MutationHandler<InferArgs<TSchema>, TReturn>, name?: string): MutationDef<TSchema, TReturn>;
+}, handlerOrDef?: MutationHandler<InferArgs<TSchema>, TReturn> | {
+    invalidates?: string[];
+    args?: TSchema;
+    public?: boolean;
+    handler: MutationHandler<InferArgs<TSchema>, TReturn>;
+}, name?: string): MutationDef<TSchema, TReturn>;
 /**
  * 커스텀 HTTP 엔드포인트를 선언적으로 등록합니다.
  * query/mutation은 RPC 패턴이지만, httpAction은 RESTful HTTP 라우트를 직접 정의합니다.

package/dist/reactive.js

@@ -36,25 +36,64 @@ export function query(key, handlerOrDef) {
     return def;
 }
 let mutationCounter = 0;
-export function mutation(invalidatesOrDef, handler, name) {
+/**
+ * mutation — 데이터 변경 함수를 선언적으로 등록합니다.
+ *
+ * 3가지 호출 방식 지원 (query와 동일한 패턴 우선):
+ *
+ * @example
+ * ```typescript
+ * // ✅ 권장: query와 동일한 (name, def) 패턴
+ * mutation("tasks.create", {
+ *     invalidates: [],
+ *     args: { title: v.string() },
+ *     handler: async (ctx, args) => { ... },
+ * });
+ *
+ * // ✅ 객체 스타일 (하위 호환)
+ * mutation({
+ *     name: "tasks.create",
+ *     invalidates: [],
+ *     handler: async (ctx) => { ... },
+ * });
+ *
+ * // ⚠️ Legacy 배열 스타일 (비권장)
+ * mutation(["tasks.list"], handler, "tasks.create");
+ * ```
+ */
+export function mutation(nameOrInvalidatesOrDef, handlerOrDef, name) {
     let invalidates;
     let argsSchema;
     let actualHandler;
     let mutName;
     let isPublic = false;
-    if (Array.isArray(invalidatesOrDef)) {
+    if (typeof nameOrInvalidatesOrDef === "string") {
+        // New primary style: mutation("name", { invalidates?, args?, public?, handler })
+        mutName = nameOrInvalidatesOrDef;
+        const def = handlerOrDef;
+        invalidates = def.invalidates || [];
+        actualHandler = def.handler;
+        argsSchema = def.args;
+        isPublic = def.public === true;
+    }
+    else if (Array.isArray(nameOrInvalidatesOrDef)) {
         // Legacy style: mutation([...], handler, "name")
-        invalidates = invalidatesOrDef;
-        actualHandler = handler;
+        invalidates = nameOrInvalidatesOrDef;
+        actualHandler = handlerOrDef;
         mutName = name || `mutation_${++mutationCounter}`;
     }
     else {
-        // New object style: mutation({ name?, invalidates, args?, public?, handler })
-        invalidates = invalidatesOrDef.invalidates;
-        actualHandler = invalidatesOrDef.handler;
-        argsSchema = invalidatesOrDef.args;
-        isPublic = invalidatesOrDef.public === true;
-        mutName = invalidatesOrDef.name || name || `mutation_${++mutationCounter}`;
+        // Object style: mutation({ name?, invalidates, args?, public?, handler })
+        invalidates = nameOrInvalidatesOrDef.invalidates;
+        actualHandler = nameOrInvalidatesOrDef.handler;
+        argsSchema = nameOrInvalidatesOrDef.args;
+        isPublic = nameOrInvalidatesOrDef.public === true;
+        mutName = nameOrInvalidatesOrDef.name || (typeof name === "string" ? name : "") || `mutation_${++mutationCounter}`;
+    }
+    // 이름 미지정 시 경고 — 디버깅 지원
+    if (mutName.startsWith("mutation_")) {
+        console.warn(`[gencow] mutation registered without explicit name → "${mutName}". ` +
+            `Use mutation("myMutation", { handler }) for better debugging.`);
     }
     const def = {
         name: mutName,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gencow/core",
-    "version": "0.1.7",
+    "version": "0.1.8",
     "description": "Gencow core library — defineQuery, defineMutation, reactive subscriptions",
     "type": "module",
     "main": "dist/index.js",

package/src/__tests__/reactive.test.ts

@@ -235,3 +235,80 @@ describe("Secure by Default — public 플래그", () => {
         expect(priv?.isPublic).toBe(false);
     });
 });
+
+// ─── mutation("name", def) 새 시그니처 테스트 ────────────────────────────────
+
+describe("mutation(name, def) — query와 동일 패턴", () => {
+    it("mutation('name', { handler })로 등록하면 name이 올바르게 설정된다", () => {
+        const m = mutation("newsig.basic", {
+            handler: async () => ({ ok: true }),
+        });
+        expect((m as any).name || (getRegisteredMutations().find(x => x.invalidates.length === 0 && x.handler === (m as any).handler) as any)?.name).toBeDefined();
+        const all = getRegisteredMutations();
+        const found = all.find(x => x.name === "newsig.basic");
+        expect(found).toBeDefined();
+        expect(found!.isPublic).toBe(false);
+    });
+
+    it("mutation('name', { public: true })로 등록하면 isPublic === true", () => {
+        const m = mutation("newsig.public", {
+            public: true,
+            handler: async () => ({ ok: true }),
+        });
+        expect(m.isPublic).toBe(true);
+    });
+
+    it("invalidates 미지정 시 빈 배열이 기본값", () => {
+        const m = mutation("newsig.noInvalidates", {
+            handler: async () => ({ ok: true }),
+        });
+        const all = getRegisteredMutations();
+        const found = all.find(x => x.name === "newsig.noInvalidates");
+        expect(found!.invalidates).toEqual([]);
+    });
+
+    it("invalidates 지정 시 올바르게 전달된다", () => {
+        const m = mutation("newsig.withInvalidates", {
+            invalidates: ["tasks.list", "tasks.get"],
+            handler: async () => ({ ok: true }),
+        });
+        const all = getRegisteredMutations();
+        const found = all.find(x => x.name === "newsig.withInvalidates");
+        expect(found!.invalidates).toEqual(["tasks.list", "tasks.get"]);
+    });
+
+    it("기존 객체 스타일도 여전히 동작한다 (하위 호환)", () => {
+        const m = mutation({
+            name: "newsig.compat.object",
+            invalidates: ["a.list"],
+            handler: async () => ({ ok: true }),
+        });
+        const all = getRegisteredMutations();
+        const found = all.find(x => x.name === "newsig.compat.object");
+        expect(found).toBeDefined();
+        expect(found!.invalidates).toEqual(["a.list"]);
+    });
+
+    it("기존 배열 스타일도 여전히 동작한다 (하위 호환)", () => {
+        const m = mutation(["b.list"], async () => ({ ok: true }), "newsig.compat.array");
+        const all = getRegisteredMutations();
+        const found = all.find(x => x.name === "newsig.compat.array");
+        expect(found).toBeDefined();
+        expect(found!.invalidates).toEqual(["b.list"]);
+    });
+
+    it("이름 미지정 시 console.warn이 호출된다", () => {
+        const warnSpy = mock(() => {});
+        const originalWarn = console.warn;
+        console.warn = warnSpy;
+
+        mutation(["c.list"], async () => ({ ok: true }));
+
+        expect(warnSpy).toHaveBeenCalled();
+        const warnMsg = warnSpy.mock.calls[0][0] as string;
+        expect(warnMsg).toContain("[gencow]");
+        expect(warnMsg).toContain("without explicit name");
+
+        console.warn = originalWarn;
+    });
+});

package/src/reactive.ts

@@ -220,9 +220,34 @@ export function query<TSchema = any, TReturn = any>(
 
 let mutationCounter = 0;
 
+/**
+ * mutation — 데이터 변경 함수를 선언적으로 등록합니다.
+ *
+ * 3가지 호출 방식 지원 (query와 동일한 패턴 우선):
+ *
+ * @example
+ * ```typescript
+ * // ✅ 권장: query와 동일한 (name, def) 패턴
+ * mutation("tasks.create", {
+ *     invalidates: [],
+ *     args: { title: v.string() },
+ *     handler: async (ctx, args) => { ... },
+ * });
+ *
+ * // ✅ 객체 스타일 (하위 호환)
+ * mutation({
+ *     name: "tasks.create",
+ *     invalidates: [],
+ *     handler: async (ctx) => { ... },
+ * });
+ *
+ * // ⚠️ Legacy 배열 스타일 (비권장)
+ * mutation(["tasks.list"], handler, "tasks.create");
+ * ```
+ */
 export function mutation<TSchema = any, TReturn = any>(
-    invalidatesOrDef: string[] | { name?: string; args?: TSchema; public?: boolean; invalidates: string[]; handler: MutationHandler<InferArgs<TSchema>, TReturn> },
-    handler?: MutationHandler<InferArgs<TSchema>, TReturn>,
+    nameOrInvalidatesOrDef: string | string[] | { name?: string; args?: TSchema; public?: boolean; invalidates: string[]; handler: MutationHandler<InferArgs<TSchema>, TReturn> },
+    handlerOrDef?: MutationHandler<InferArgs<TSchema>, TReturn> | { invalidates?: string[]; args?: TSchema; public?: boolean; handler: MutationHandler<InferArgs<TSchema>, TReturn> },
     name?: string
 ): MutationDef<TSchema, TReturn> {
     let invalidates: string[];
@@ -231,19 +256,36 @@ export function mutation<TSchema = any, TReturn = any>(
     let mutName: string;
     let isPublic = false;
 
-    if (Array.isArray(invalidatesOrDef)) {
+    if (typeof nameOrInvalidatesOrDef === "string") {
+        // New primary style: mutation("name", { invalidates?, args?, public?, handler })
+        mutName = nameOrInvalidatesOrDef;
+        const def = handlerOrDef as { invalidates?: string[]; args?: TSchema; public?: boolean; handler: MutationHandler<InferArgs<TSchema>, TReturn> };
+        invalidates = def.invalidates || [];
+        actualHandler = def.handler;
+        argsSchema = def.args;
+        isPublic = def.public === true;
+    } else if (Array.isArray(nameOrInvalidatesOrDef)) {
         // Legacy style: mutation([...], handler, "name")
-        invalidates = invalidatesOrDef;
-        actualHandler = handler!;
+        invalidates = nameOrInvalidatesOrDef;
+        actualHandler = handlerOrDef as MutationHandler<InferArgs<TSchema>, TReturn>;
         mutName = name || `mutation_${++mutationCounter}`;
     } else {
-        // New object style: mutation({ name?, invalidates, args?, public?, handler })
-        invalidates = invalidatesOrDef.invalidates;
-        actualHandler = invalidatesOrDef.handler;
-        argsSchema = invalidatesOrDef.args;
-        isPublic = invalidatesOrDef.public === true;
-        mutName = invalidatesOrDef.name || name || `mutation_${++mutationCounter}`;
+        // Object style: mutation({ name?, invalidates, args?, public?, handler })
+        invalidates = nameOrInvalidatesOrDef.invalidates;
+        actualHandler = nameOrInvalidatesOrDef.handler;
+        argsSchema = nameOrInvalidatesOrDef.args;
+        isPublic = nameOrInvalidatesOrDef.public === true;
+        mutName = nameOrInvalidatesOrDef.name || (typeof name === "string" ? name : "") || `mutation_${++mutationCounter}`;
     }
+
+    // 이름 미지정 시 경고 — 디버깅 지원
+    if (mutName.startsWith("mutation_")) {
+        console.warn(
+            `[gencow] mutation registered without explicit name → "${mutName}". ` +
+            `Use mutation("myMutation", { handler }) for better debugging.`
+        );
+    }
+
     const def: MutationDef<TSchema, TReturn> & { name: string } = {
         name: mutName,
         invalidates,