@dr_nikson/effect-grpc 0.2.0-mvp-9971208edee70b39058f12d8c2a1fcfaeecd3b51 → 3.0.0-alpha.1

package/dist/protocGenPlugin.js

@@ -1,4 +1,3 @@
-// #!/usr/bin/env -S node
 import { createEcmaScriptPlugin, safeIdentifier } from "@bufbuild/protoplugin";
 import packageJson from "../package.json" with { type: "json" };
 export const protocGenEffectGrpc = createEcmaScriptPlugin({
@@ -10,7 +9,9 @@ function generateTs(schema) {
     for (const file of schema.files) {
         const f = schema.generateFile(file.name + "_effect.ts");
         f.preamble(file);
-        file.services.forEach(service => generateEffectService(f, service));
+        // Extract basename from file path for import examples
+        const fileBasename = file.name.split('/').pop() || file.name;
+        file.services.forEach(service => generateEffectService(f, service, fileBasename));
         /*
                 for (const service of file.services) {
                     f.print(f.jsDoc(service));
@@ -61,206 +62,418 @@ function generateTs(schema) {
                 }*/
     }
 }
-function generateEffectService(f, service) {
+function generateEffectService(f, service, fileBasename) {
     const importEffect = f.import("Effect", "effect");
     const importContext = f.import("Context", "effect");
     const importLayer = f.import("Layer", "effect");
-    const importHandlerContext = f.import("HandlerContext", "@connectrpc/connect");
+    const importScope = f.import("Scope", "effect");
     const importEffectGrpcService = f.import("EffectGrpcServer", packageJson.name);
+    const importGrpcException = f.import("GrpcException", packageJson.name);
     const importService = f.importSchema(service);
     const serviceId = service.typeName;
-    const serviceIdSymbol = safeIdentifier(service.name + "Id");
+    const serviceIdSymbol = safeIdentifier(service.name + "ProtoId");
     const serviceSymbol = safeIdentifier(service.name + "Service");
     const grpcServiceSymbol = safeIdentifier(service.name + "GrpcService");
-    const serviceTagSymbol = safeIdentifier(service.name + "Tag");
+    const serviceTagSymbol = safeIdentifier(service.name + "ServiceTag");
+    const serviceLiveLayerSymbol = safeIdentifier(service.name.charAt(0).toLowerCase() + service.name.slice(1) + "ServiceLiveLayer");
     const makeTagSymbol = safeIdentifier("make" + service.name + "ServiceTag");
-    const makeLiveLayerSymbol = safeIdentifier("make" + service.name + "LiveLayer");
+    const makeLiveLayerSymbol = safeIdentifier("make" + service.name + "ServiceLiveLayer");
+    // Generate service ID constant with JSDoc
+    f.print("/**");
+    f.print(" * Unique identifier for the ", service.name, " gRPC service.");
+    f.print(" *");
+    f.print(" * This constant represents the fully qualified service name from the Protocol Buffer definition.");
+    f.print(" * It's used to identify and wire gRPC dependencies.");
+    f.print(" *");
+    f.print(" * @generated from service ", service.typeName);
+    f.print(" */");
     f.print(f.export("const", serviceIdSymbol), " = ", f.string(serviceId), " as const;");
     f.print(f.export("type", serviceIdSymbol), " = typeof ", serviceIdSymbol, ";");
     f.print();
-    f.print(f.jsDoc(service));
-    f.print(f.export("interface", serviceSymbol), "<Ctx> {");
+    // Generate comprehensive JSDoc for service interface
+    f.print("/**");
+    f.print(" * gRPC service interface.");
+    f.print(" *");
+    f.print(" * @typeParam Ctx - The type of context passed to service methods. Use this to inject");
+    f.print(" *                  dependencies or pass request-scoped data (e.g., authentication info)");
+    f.print(" *");
+    f.print(" * @example");
+    f.print(" * ```typescript");
+    f.print(" * import { Effect } from \"effect\";");
+    f.print(" * import * as effectProto from \"./" + fileBasename + "_effect.js\";");
+    f.print(" *");
+    f.print(" * // Simple implementation with default context");
+    f.print(" * const service: effectProto.", serviceSymbol, " = {");
+    if (service.methods.length > 0 && service.methods[0] !== undefined) {
+        const firstMethod = service.methods[0];
+        f.print(" *   ", firstMethod.localName, ": (request) =>");
+        f.print(" *     Effect.succeed({})");
+    }
+    f.print(" * };");
+    f.print(" * ```");
+    f.print(" *");
+    f.print(" * @generated from service ", service.typeName);
+    f.print(" */");
+    f.print(f.export("interface", serviceSymbol), "<Ctx = any> {");
     service.methods.forEach(generateServerMethod);
     f.print("}");
-    /**
-     * @example
-     * ```typescript
-     * export const DebugAPIService: {
-     *     makeTag<Ctx>(ctxKey: string): DebugAPITag<Ctx>;
-     *
-     *     liveLayer<Ctx>(service: DebugAPIService<Ctx>):
-     *         <Tag extends DebugAPITag<Ctx>>(tag: Tag) => Layer.Layer<Context.Tag.Identifier<Tag>, never, never>;
-     * } = {
-     *     makeTag: makeDebugAPIServiceTag,
-     *     liveLayer: makeDebugApiLiveLayer
-     * };
-     * ```
-     */
-    f.print(f.export("const", serviceSymbol), ": {");
-    f.print("  makeTag<Ctx>(ctxKey: string): ", serviceTagSymbol, "<Ctx>;");
     f.print();
-    f.print("  liveLayer<Ctx>(");
-    f.print("    service: ", serviceSymbol, "<Ctx>");
-    f.print("  ): <Tag extends ", serviceTagSymbol, "<Ctx>>(tag: Tag) => ", importLayer, ".Layer<", importContext, ".Tag.Identifier<Tag>, never, never>;");
-    f.print("} = {");
-    f.print("    makeTag: ", makeTagSymbol, ",");
-    f.print("    liveLayer: ", makeLiveLayerSymbol);
-    f.print("};");
+    // Generate direct exported layer function with JSDoc
+    f.print("/**");
+    f.print(" * Creates a Layer that provides a gRPC service implementation.");
+    f.print(" *");
+    f.print(" * This function takes your service implementation and wraps it in a Layer that can be");
+    f.print(" * composed with other layers to build your application. The returned function accepts");
+    f.print(" * a Context.Tag to identify the service in the Effect context.");
+    f.print(" *");
+    f.print(" * @typeParam Ctx - The context type used by your service implementation");
+    f.print(" *");
+    f.print(" * @param tag - Context tag to identify the service");
+    f.print(" * @param service - Your implementation of the ", serviceSymbol, " interface");
+    f.print(" * @returns A Layer providing the gRPC service");
+    f.print(" *");
+    f.print(" * @example");
+    f.print(" * ```typescript");
+    f.print(" * import { Effect, Layer } from \"effect\";");
+    f.print(" * import * as effectProto from \"./" + fileBasename + "_effect.js\";");
+    f.print(" *");
+    f.print(" * // Define your service implementation");
+    f.print(" * const myService: effectProto.", serviceSymbol, " = {");
+    if (service.methods.length > 0 && service.methods[0] !== undefined) {
+        const firstMethod = service.methods[0];
+        f.print(" *   ", firstMethod.localName, ": (request) =>");
+        f.print(" *     Effect.succeed({})");
+    }
+    f.print(" * };");
+    f.print(" *");
+    f.print(" * // Create the service layer");
+    f.print(" * const ServiceLayer = effectProto.", serviceLiveLayerSymbol, "(effectProto.", serviceTagSymbol, ", myService);");
+    f.print(" * ```");
+    f.print(" *");
+    f.print(" * @generated from service ", service.typeName);
+    f.print(" */");
+    f.print(f.export("const", serviceLiveLayerSymbol), ": {");
+    f.print("  <Tag extends ", serviceTagSymbol, "<Ctx>, Ctx>(");
+    f.print("    tag: Tag,");
+    f.print("    service: ", serviceSymbol, "<Ctx>,");
+    f.print("  ): ", importLayer, ".Layer<", importContext, ".Tag.Identifier<Tag>>;");
+    f.print("} = ", makeLiveLayerSymbol, ";");
+    f.print();
+    // Generate type aliases with JSDoc
+    f.print("/**");
+    f.print(" * Type alias for the wrapped gRPC service.");
+    f.print(" *");
+    f.print(" * This represents the Effect-wrapped version of your service implementation,");
+    f.print(" * ready to be registered with a gRPC server.");
+    f.print(" *");
+    f.print(" * @typeParam Ctx - The context type used by the service");
+    f.print(" *");
+    f.print(" * @generated from service ", service.typeName);
+    f.print(" */");
+    f.print(f.export("type", grpcServiceSymbol), "<Ctx = any>", " = ", importEffectGrpcService, ".GrpcService<", serviceIdSymbol, ", typeof ", importService, ", Ctx>");
+    f.print();
+    // export type DebugAPIServiceTag<Ctx = any> = Context.Tag<DebugAPIGrpcService<Ctx>, DebugAPIGrpcService<Ctx>>
+    f.print("/**");
+    f.print(" * Type alias for the service Context.Tag.");
+    f.print(" *");
+    f.print(" * Used to identify and retrieve the service from the Effect context.");
+    f.print(" *");
+    f.print(" * @typeParam Ctx - The context type used by the service");
+    f.print(" *");
+    f.print(" * @generated from service ", service.typeName);
+    f.print(" */");
+    f.print(f.export("type", serviceTagSymbol), "<Ctx = any>", " = ", importContext, ".Tag<", grpcServiceSymbol, "<Ctx>, ", grpcServiceSymbol, "<Ctx>>");
+    f.print();
+    // Generate ServiceTag constant with comprehensive JSDoc
+    f.print("/**");
+    f.print(" * Context.Tag for identifying the ", service.name, " service implementation.");
+    f.print(" *");
+    f.print(" * This tag is used to provide and retrieve the service from the Effect context.");
+    f.print(" * It supports both default (any) context and typed context via the function overload.");
+    f.print(" *");
+    f.print(" * @example");
+    f.print(" * ```typescript");
+    f.print(" * import { Effect } from \"effect\";");
+    f.print(" * import * as effectProto from \"./" + fileBasename + "_effect.js\";");
+    f.print(" *");
+    f.print(" * // Use default context tag");
+    f.print(" * const myService = {");
+    if (service.methods.length > 0 && service.methods[0] !== undefined) {
+        const firstMethod = service.methods[0];
+        f.print(" *   ", firstMethod.localName, ": (request) => Effect.succeed({})");
+    }
+    f.print(" * };");
+    f.print(" * const ServiceLayer = effectProto.", serviceLiveLayerSymbol, "(effectProto.", serviceTagSymbol, ", myService);");
+    f.print(" * ```");
+    f.print(" *");
+    f.print(" * @example");
+    f.print(" * ```typescript");
+    f.print(" * import { Effect } from \"effect\";");
+    f.print(" * import * as effectProto from \"./" + fileBasename + "_effect.js\";");
+    f.print(" *");
+    f.print(" * // Create a typed context tag");
+    f.print(" * interface MyContext {");
+    f.print(" *   userId: string;");
+    f.print(" * }");
+    f.print(" *");
+    f.print(" * const TypedServiceTag = effectProto.", serviceTagSymbol, "<MyContext>(\"MyContext\");");
+    f.print(" * ```");
+    f.print(" *");
+    f.print(" * @generated from service ", service.typeName);
+    f.print(" */");
+    f.print(f.export("const", serviceTagSymbol), ": ", serviceTagSymbol, " & {");
+    f.print("  <Ctx>(ctxKey: string): ", serviceTagSymbol, "<Ctx>;");
+    f.print("} = Object.assign(", makeTagSymbol, "(), ", makeTagSymbol, ");");
     f.print();
-    // export type DebugAPIGrpcService<Ctx = HandlerContext> = EffectGrpcServer.GrpcService<"DebugAPI", typeof proto.DebugAPI, Ctx>
-    f.print(f.export("type", grpcServiceSymbol), "<Ctx = ", importHandlerContext, ">", " = ", importEffectGrpcService, `.GrpcService<"`, service.typeName, `", typeof `, importService, ", Ctx>");
-    // export type DebugAPITag<Ctx> = Context.Tag<DebugAPIGrpcService<Ctx>, DebugAPIGrpcService<Ctx>>
-    f.print(f.export("type", serviceTagSymbol), "<Ctx>", " = ", importContext, ".Tag<", grpcServiceSymbol, "<Ctx>, ", grpcServiceSymbol, "<Ctx>>");
     /**
      * @example
      * ```typescript
-     * function makeDebugAPIServiceTag<Ctx>(ctxKey: string & keyof Ctx): DebugAPITag<Ctx> {
-     *     return Context.GenericTag<DebugAPIGrpcService<Ctx>, DebugAPIGrpcService<Ctx>>(`${proto.DebugAPI.typeName}<${ctxKey}}>`);
+     * function makeDebugAPIServiceTag<Ctx = any>(ctxKey: string = "any"): DebugAPITag<Ctx> {
+     *     return Context.GenericTag<DebugAPIGrpcService<Ctx>>(`${proto.DebugAPI.typeName}<${ctxKey}}>`);
      * }
      * ```
      */
-    f.print("function ", makeTagSymbol, "<Ctx>(ctxKey: string): ", serviceTagSymbol, "<Ctx> {");
+    f.print("function ", makeTagSymbol, "<Ctx = any>(ctxKey: string = ", f.string("any"), "): ", serviceTagSymbol, "<Ctx> {");
     f.print("  return ", importContext, ".GenericTag<", grpcServiceSymbol, "<Ctx>>(`", service.typeName, "<${ctxKey}>`);");
     f.print("}");
     f.print();
-    /**
-     * @example
-     * ```typescript
-     * function makeDebugApiLiveLayer<Ctx>(service: DebugAPIService<Ctx>) {
-     *     return <Tag extends DebugAPITag<Ctx>>(tag: Tag) => {
-     *         type Proto = typeof proto.DebugAPI;
-     *
-     *         const instance: DebugAPIGrpcService<Ctx> = EffectGrpcServer.GrpcService("DebugAPI" as const, proto.DebugAPI)(
-     *             (executor: EffectGrpcServer.Executor<Ctx>): ServiceImpl<Proto> => {
-     *                 return {
-     *                     getDebugInfo: (req: proto.GetDebugInfoRequest, ctx: HandlerContext) => {
-     *                         return executor.unary(
-     *                             req,
-     *                             ctx,
-     *                             (req, ctx) => service.getDebugInfo(req, ctx)
-     *                         );
-     *                     }
-     *                 } as ServiceImpl<Proto>;
-     *             }
-     *         );
-     *
-     *         return Layer.succeed(tag, instance);
-     *
-     *     }
-     * }
-     * ```
-     */
-    f.print("function ", makeLiveLayerSymbol, "<Ctx>(service: ", serviceSymbol, "<Ctx>) {");
-    f.print("  return <Tag extends ", serviceTagSymbol, "<Ctx>>(tag: Tag) => {");
-    f.print();
-    f.print("    const instance: ", grpcServiceSymbol, "<Ctx> = ", importEffectGrpcService, '.GrpcService("', service.typeName, '" as const, ', importService, ")(");
-    f.print("      (executor) => ({");
+    // Generate implementation function
+    f.print("function ", makeLiveLayerSymbol, "<Tag extends ", serviceTagSymbol, "<Ctx>, Ctx>(");
+    f.print("  tag: Tag,");
+    f.print("  service: ", serviceSymbol, "<Ctx>,");
+    f.print("): ", importLayer, ".Layer<", importContext, ".Tag.Identifier<Tag>> {");
+    f.print("  const instance: ", grpcServiceSymbol, "<Ctx> = ", importEffectGrpcService, ".GrpcService(");
+    f.print("    ", serviceIdSymbol, ",");
+    f.print("    ", importService, ",");
+    f.print("  )((executor) => ({");
     service.methods.forEach((method) => {
         if (method.methodKind === "unary") {
-            f.print("        ", method.localName, ": (req, ctx) => executor.unary(req, ctx, (req, ctx) => service.", method.localName, "(req, ctx))", ",");
+            f.print("    ", method.localName, ": (req, ctx) =>");
+            f.print("      executor.unary(req, ctx, (req, ctx) => service.", method.localName, "(req, ctx)),");
         }
     });
-    f.print("      })");
-    f.print("    );");
+    f.print("  }));");
     f.print();
-    f.print("    return ", importLayer, ".succeed(tag, instance);");
-    f.print("  };");
+    f.print("  return ", importLayer, ".succeed(tag, instance);");
     f.print("}");
     f.print();
     const clientSymbol = safeIdentifier(service.name + "Client");
-    /**
-     * @example
-     * ```typescript
-     * export interface DebugAPIClient<Meta> {
-     *     getDebugInfo(
-     *         request: MessageInitShape<typeof proto.GetDebugInfoRequestSchema>,
-     *         meta: Meta,
-     *     ): Effect.Effect<proto.GetDebugInfoResponse>
-     * }
-     * ```
-     */
-    f.print(f.jsDoc(service));
-    f.print(f.export("interface", clientSymbol), "<Meta> {");
-    service.methods.forEach(generateClientMethod);
-    f.print("}");
-    /**
-     * @example
-     * ```typescript
-     * export const DebugAPIClient: {
-     *     makeTag<Meta>(metaKey: string): DebugAPIClientTag<Meta>
-     *
-     *     liveLayer<Meta>(transformMeta: (meta: Meta) => RequestMeta):
-     *         <Tag extends DebugAPIClientTag<Meta>>(tag: Tag) => Layer.Layer<Context.Tag.Identifier<Tag>, never, EffectGrpcClient.GrpcClient>
-     * } = {
-     *     makeTag: makeDebugAPIClientTag,
-     *     liveLayer: makeDebugApiClientLiveLayer,
-     * }
-     * ```
-     */
     const importEffectGrpcClient = f.import("EffectGrpcClient", packageJson.name);
     const clientTagSymbol = safeIdentifier(service.name + "ClientTag");
+    const clientLiveLayerSymbol = safeIdentifier(service.name.charAt(0).toLowerCase() + service.name.slice(1) + "ClientLiveLayer");
     const configTagSymbol = safeIdentifier(service.name + "ConfigTag");
     const makeClientTagSymbol = safeIdentifier("make" + service.name + "ClientTag");
     const makeClientLiveLayerSymbol = safeIdentifier("make" + service.name + "ClientLiveLayer");
-    f.print(f.export("const", clientSymbol), ": {");
-    f.print("  makeTag<Meta>(metaKey: string): ", clientTagSymbol, "<Meta>;");
+    // Generate comprehensive JSDoc for client interface
+    f.print("/**");
+    f.print(" * Client interface for making gRPC calls to ", service.name, " service.");
+    f.print(" *");
+    f.print(" * This interface defines the client-side methods for calling the gRPC service.");
+    f.print(" * Each method accepts a request message and metadata, and returns an Effect that");
+    f.print(" * produces the response or fails with an error.");
+    f.print(" *");
+    f.print(" * @typeParam Meta - The type of metadata to pass with each request. This can be used");
+    f.print(" *                   for authentication tokens, tracing headers, or other per-request data.");
+    f.print(" *");
+    f.print(" * @example");
+    f.print(" * ```typescript");
+    f.print(" * import { Effect } from \"effect\";");
+    f.print(" * import * as effectProto from \"./" + fileBasename + "_effect.js\";");
+    f.print(" *");
+    f.print(" * // Use the client in an Effect");
+    f.print(" * const program = Effect.gen(function* () {");
+    f.print(" *   const client = yield* effectProto.", clientTagSymbol, ";");
+    if (service.methods.length > 0 && service.methods[0] !== undefined) {
+        const firstMethod = service.methods[0];
+        f.print(" *   const response = yield* client.", firstMethod.localName, "({}, {});");
+        f.print(" *   return response;");
+    }
+    f.print(" * });");
+    f.print(" * ```");
+    f.print(" *");
+    f.print(" * @generated from service ", service.typeName);
+    f.print(" */");
+    f.print(f.export("interface", clientSymbol), "<Meta> {");
+    service.methods.forEach(generateClientMethod);
+    f.print("}");
+    f.print();
+    // Generate ClientTag type with JSDoc
+    f.print("/**");
+    f.print(" * Type alias for the client Context.Tag.");
+    f.print(" *");
+    f.print(" * Used to identify and retrieve the client from the Effect context.");
+    f.print(" *");
+    f.print(" * @typeParam Meta - The metadata type used by the client");
+    f.print(" *");
+    f.print(" * @generated from service ", service.typeName);
+    f.print(" */");
+    f.print(f.export("type", clientTagSymbol), "<Meta = any>", " = ", importContext, ".Tag<", clientSymbol, "<Meta>, ", clientSymbol, "<Meta>>");
+    f.print();
+    // Generate ClientTag constant with comprehensive JSDoc
+    f.print("/**");
+    f.print(" * Context.Tag for identifying the ", service.name, " client.");
+    f.print(" *");
+    f.print(" * This tag is used to provide and retrieve the gRPC client from the Effect context.");
+    f.print(" * It supports both default (any) metadata and typed metadata via the function overload.");
+    f.print(" *");
+    f.print(" * @example");
+    f.print(" * ```typescript");
+    f.print(" * import { Effect, Layer } from \"effect\";");
+    f.print(" * import * as effectProto from \"./" + fileBasename + "_effect.js\";");
+    f.print(" * import { EffectGrpcClient } from \"@dr_nikson/effect-grpc\";");
+    f.print(" *");
+    f.print(" * // Use default metadata type");
+    f.print(" * const ClientLayer = effectProto.", clientLiveLayerSymbol, "(effectProto.", clientTagSymbol, ");");
+    f.print(" *");
+    f.print(" * // Use the client");
+    f.print(" * const program = Effect.gen(function* () {");
+    f.print(" *   const client = yield* effectProto.", clientTagSymbol, ";");
+    if (service.methods.length > 0 && service.methods[0] !== undefined) {
+        const firstMethod = service.methods[0];
+        f.print(" *   return yield* client.", firstMethod.localName, "({}, {});");
+    }
+    f.print(" * });");
+    f.print(" * ```");
+    f.print(" *");
+    f.print(" * @example");
+    f.print(" * ```typescript");
+    f.print(" * import { Effect, Layer } from \"effect\";");
+    f.print(" * import * as effectProto from \"./" + fileBasename + "_effect.js\";");
+    f.print(" *");
+    f.print(" * // Create a typed metadata tag");
+    f.print(" * interface RequestMeta {");
+    f.print(" *   userId: string;");
+    f.print(" *   traceId: string;");
+    f.print(" * }");
+    f.print(" *");
+    f.print(" * const TypedClientTag = effectProto.", clientTagSymbol, "<RequestMeta>(\"RequestMeta\");");
+    f.print(" * ```");
+    f.print(" *");
+    f.print(" * @generated from service ", service.typeName);
+    f.print(" */");
+    f.print(f.export("const", clientTagSymbol), ": ", clientTagSymbol, " & {");
+    f.print("  <Meta>(metaKey: string): ", clientTagSymbol, "<Meta>;");
+    f.print("} = Object.assign(", makeClientTagSymbol, "<any>(", f.string("any"), "), ", makeClientTagSymbol, ");");
     f.print();
-    f.print("  liveLayer<Tag extends ", clientTagSymbol, "<Meta>, Meta>(");
+    // Generate clientLiveLayer function with comprehensive JSDoc
+    f.print("/**");
+    f.print(" * Creates a Layer that provides a gRPC client for the ", service.name, " service.");
+    f.print(" *");
+    f.print(" * This function creates a client that can make gRPC calls to the service.");
+    f.print(" * It has two overloads:");
+    f.print(" * 1. Simple version: Just pass the tag (uses default empty metadata)");
+    f.print(" * 2. Advanced version: Pass a metadata transformer function and the tag");
+    f.print(" *");
+    f.print(" * The client layer requires:");
+    f.print(" * - ", configTagSymbol, ": Configuration with the server URL");
+    f.print(" * - EffectGrpcClient.GrpcClientRuntime: The gRPC runtime");
+    f.print(" * - Scope.Scope: For resource management");
+    f.print(" *");
+    f.print(" * @example");
+    f.print(" * ```typescript");
+    f.print(" * import { Effect, Layer } from \"effect\";");
+    f.print(" * import * as effectProto from \"./" + fileBasename + "_effect.js\";");
+    f.print(" * import { EffectGrpcClient } from \"@dr_nikson/effect-grpc\";");
+    f.print(" *");
+    f.print(" * // Simple usage with default metadata");
+    f.print(" * const ClientLayer = effectProto.", clientLiveLayerSymbol, "(effectProto.", clientTagSymbol, ");");
+    f.print(" *");
+    f.print(" * // Configuration layer");
+    f.print(" * const ConfigLayer = Layer.succeed(");
+    f.print(" *   effectProto.", configTagSymbol, ",");
+    f.print(" *   { baseUrl: new URL(\"http://localhost:50051\") }");
+    f.print(" * );");
+    f.print(" * ```");
+    f.print(" *");
+    f.print(" * @example");
+    f.print(" * ```typescript");
+    f.print(" * import { Effect } from \"effect\";");
+    f.print(" * import * as effectProto from \"./" + fileBasename + "_effect.js\";");
+    f.print(" *");
+    f.print(" * // Advanced usage with metadata transformation");
+    f.print(" * interface AppMeta {");
+    f.print(" *   userId: string;");
+    f.print(" *   authToken: string;");
+    f.print(" * }");
+    f.print(" *");
+    f.print(" * const AppClientTag = effectProto.", clientTagSymbol, "<AppMeta>(\"AppMeta\");");
+    f.print(" *");
+    f.print(" * // Transform app metadata to gRPC headers");
+    f.print(" * const ClientLayer = effectProto.", clientLiveLayerSymbol, "(");
+    f.print(" *   (meta: AppMeta) => ({");
+    f.print(" *     headers: {");
+    f.print(" *       \"authorization\": `Bearer ${meta.authToken}`,");
+    f.print(" *       \"x-user-id\": meta.userId");
+    f.print(" *     }");
+    f.print(" *   }),");
+    f.print(" *   AppClientTag");
+    f.print(" * );");
+    f.print(" * ```");
+    f.print(" *");
+    f.print(" * @generated from service ", service.typeName);
+    f.print(" */");
+    f.print(f.export("const", clientLiveLayerSymbol), ": {");
+    f.print("  <Tag extends ", clientTagSymbol, "<Meta>, Meta>(");
     f.print("    transformMeta: (meta: Meta) => ", importEffectGrpcClient, ".RequestMeta,");
-    f.print("    tag: Tag");
+    f.print("    tag: Tag,");
     f.print("  ): ", importLayer, ".Layer<");
     f.print("    ", importContext, ".Tag.Identifier<Tag>,");
     f.print("    never,");
-    f.print("    ", importContext, ".Tag.Identifier<", configTagSymbol, "> | ", importEffectGrpcClient, ".GrpcClientRuntime");
+    f.print("    ", configTagSymbol, "[\"Identifier\"] | ", importEffectGrpcClient, ".GrpcClientRuntime | ", importScope, ".Scope");
     f.print("  >;");
     f.print();
-    f.print("  liveLayer<Tag extends ", clientTagSymbol, "<object>>(");
-    f.print("    tag: Tag");
+    f.print("  <Tag extends ", clientTagSymbol, ">(");
+    f.print("    tag: Tag,");
     f.print("  ): ", importLayer, ".Layer<");
     f.print("    ", importContext, ".Tag.Identifier<Tag>,");
     f.print("    never,");
-    f.print("    ", importContext, ".Tag.Identifier<", configTagSymbol, "> | ", importEffectGrpcClient, ".GrpcClientRuntime");
+    f.print("    ", configTagSymbol, "[\"Identifier\"] | ", importEffectGrpcClient, ".GrpcClientRuntime | ", importScope, ".Scope");
     f.print("  >;");
-    f.print("} = {");
-    f.print("  makeTag: ", makeClientTagSymbol, ",");
-    f.print("  liveLayer: ", makeClientLiveLayerSymbol, ",");
-    f.print("};");
-    f.print();
-    // export type DebugAPIClientTag<Meta> = Context.Tag<DebugAPIClient<Meta>, DebugAPIClient<Meta>>
-    f.print(f.export("type", clientTagSymbol), "<Meta>", " = ", importContext, ".Tag<", clientSymbol, "<Meta>, ", clientSymbol, "<Meta>>");
+    f.print("} = ", makeClientLiveLayerSymbol, ";");
     f.print();
-    // export type HelloWorldAPIConfigTag = Context.Tag<EffectGrpcClient.GrpcClientConfig<HelloWorldAPIId>, EffectGrpcClient.GrpcClientConfig<HelloWorldAPIId>>
+    // Generate ConfigTag type with JSDoc
+    f.print("/**");
+    f.print(" * Type alias for the client configuration Context.Tag.");
+    f.print(" *");
+    f.print(" * This tag provides the configuration required by the gRPC client,");
+    f.print(" * such as the server URL and connection options.");
+    f.print(" *");
+    f.print(" * @generated from service ", service.typeName);
+    f.print(" */");
     f.print(f.export("type", configTagSymbol), " = ", importContext, ".Tag<", importEffectGrpcClient, ".GrpcClientConfig<", serviceIdSymbol, ">, ", importEffectGrpcClient, ".GrpcClientConfig<", serviceIdSymbol, ">>");
-    // export const HelloWorldAPIConfigTag: HelloWorldAPIConfigTag = EffectGrpcClient.GrpcClientConfig.makeTag(HelloWorldAPIId);
+    f.print();
+    // Generate ConfigTag constant with comprehensive JSDoc
+    f.print("/**");
+    f.print(" * Context.Tag for the ", service.name, " client configuration.");
+    f.print(" *");
+    f.print(" * This tag is used to provide the gRPC client configuration, which includes:");
+    f.print(" * - baseUrl: The URL of the gRPC server (e.g., \"http://localhost:50051\")");
+    f.print(" * - Additional connection options (timeouts, interceptors, etc.)");
+    f.print(" *");
+    f.print(" * You must provide this configuration as a Layer when using the client.");
+    f.print(" *");
+    f.print(" * @example");
+    f.print(" * ```typescript");
+    f.print(" * import { Layer } from \"effect\";");
+    f.print(" * import * as effectProto from \"./" + fileBasename + "_effect.js\";");
+    f.print(" *");
+    f.print(" * // Simple configuration with just the base URL");
+    f.print(" * const ConfigLayer = Layer.succeed(");
+    f.print(" *   effectProto.", configTagSymbol, ",");
+    f.print(" *   { baseUrl: new URL(\"http://localhost:50051\") }");
+    f.print(" * );");
+    f.print(" * ```");
+    f.print(" *");
+    f.print(" * @generated from service ", service.typeName);
+    f.print(" */");
     f.print(f.export("const", configTagSymbol), ": ", configTagSymbol, " = ", importEffectGrpcClient, ".GrpcClientConfig.makeTag(", serviceIdSymbol, ");");
     f.print();
-    // function makeDebugAPIClientTag<Meta>(metaKey: string): DebugAPIClientTag<Meta>
+    // Generate makeClientTag helper function
     f.print("function ", makeClientTagSymbol, "<Meta>(metaKey: string): ", clientTagSymbol, "<Meta> {");
-    f.print("  return ", importContext, ".GenericTag<", clientSymbol, "<Meta>>(`", service.typeName, "Client<${metaKey}>`);");
+    f.print("  return ", importContext, ".GenericTag<", clientSymbol, "<Meta>>(`${", serviceIdSymbol, "}<${metaKey}>`);");
     f.print("}");
     f.print();
-    /**
-     * @example
-     * ```typescript
-     * function makeDebugApiClientLiveLayer<Meta>(transformMeta: (meta: Meta) => RequestMeta) {
-     *     return <Tag extends DebugAPIClientTag<Meta>>(tag: Tag) => {
-     *         const prog = Effect.gen(function* () {
-     *             const grpcService = yield* EffectGrpcClient.GrpcClient
-     *             const executor = grpcService.makeExecutor(proto.DebugAPI, ["getDebugInfo"]);
-     *
-     *             return {
-     *                 getDebugInfo(req, meta) {
-     *                     return executor.getDebugInfo(req, meta ?? transformMeta(meta));
-     *                 },
-     *             } as DebugAPIClient<Meta>;
-     *         });
-     *
-     *         return Layer.effect(tag, prog);
-     *     }
-     * }
-     * ```
-     */
-    // function makeDebugAPIClientLiveLayer<Tag extends DebugAPIClientTag<Meta>, Meta = object>(...args: readonly [(meta: Meta) => RequestMeta, Tag] | readonly [Tag])
+    // Generate client implementation function with overload handling
     f.print("function ", makeClientLiveLayerSymbol, "<Tag extends ", clientTagSymbol, "<Meta>, Meta = object>(");
     f.print("  ...args: readonly [(meta: Meta) => ", importEffectGrpcClient, ".RequestMeta, Tag] | readonly [Tag]");
     f.print(") {");
@@ -324,7 +537,7 @@ function generateEffectService(f, service) {
             case "unary":
                 f.print();
                 f.print(f.jsDoc(method, "  "));
-                f.print("  ", method.localName, "(request: ", inputType, ", ctx: Ctx): ", importEffect, ".Effect<", importMessageInitShape, "<typeof ", outputDesc, ">>;");
+                f.print("  ", method.localName, "(request: ", inputType, ", ctx: Ctx): ", importEffect, ".Effect<", importMessageInitShape, "<typeof ", outputDesc, ">, ", importGrpcException, ".GrpcException>;");
                 return;
             default:
                 f.print("// Method[", method.localName, "] wasn't generated: methodKind is not yet supported [", method.methodKind, "]");