[TCGC] Add InitializedBy.none to support omitting generated client constructors

.chronus/changes/copilot-add-none-to-initializedby-enum-2026-1-2-6-28-11.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@azure-tools/typespec-client-generator-core"
+---
+
+Added `InitializedBy.none` (value 0) to allow TypeSpec authors to indicate that client constructors should be omitted and hand-written. Note: The internal `InitializedByFlags.Default` value changed from `0` to `-1` to accommodate this addition.

packages/typespec-client-generator-core/lib/decorators.tsp

@@ -523,6 +523,11 @@ extern dec useSystemTextJsonConverter(target: Model, scope?: valueof string);
  * InitializedBy value.
  */
 enum InitializedBy {
+  /**
+   * The client initialization should be omitted and hand-written.
+   */
+  none: 0,
+
   /**
    * The client could be initialized individually.
    */

packages/typespec-client-generator-core/src/clients.ts

@@ -344,8 +344,9 @@ function createSdkClientInitializationType<
         result.parameters.push(clientParameter);
       }
     }
-    if (initializationOptions?.initializedBy) {
+    if (initializationOptions?.initializedBy !== undefined) {
       if (
+        initializationOptions.initializedBy !== InitializedByFlags.None &&
         client.kind === "SdkClient" &&
         (initializationOptions.initializedBy & InitializedByFlags.Parent) ===
           InitializedByFlags.Parent
@@ -361,6 +362,7 @@ function createSdkClientInitializationType<
           }),
         );
       } else if (
+        initializationOptions.initializedBy !== InitializedByFlags.None &&
         client.kind === "SdkOperationGroup" &&
         initializationOptions.initializedBy === InitializedByFlags.Individually
       ) {

packages/typespec-client-generator-core/src/decorators.ts

@@ -1023,13 +1023,15 @@ export const $clientInitialization: ClientInitializationDecorator = (
     if (options.properties.get("initializedBy")) {
       const value = options.properties.get("initializedBy")!.type;
 
-      const isValidValue = (value: number): boolean => value === 1 || value === 2;
+      const isValidValue = (value: number): boolean => value === 0 || value === 1 || value === 2;
 
       if (value.kind === "EnumMember") {
         if (typeof value.value !== "number" || !isValidValue(value.value)) {
           reportDiagnostic(context.program, {
             code: "invalid-initialized-by",
-            format: { message: "Please use `InitializedBy` enum to set the value." },
+            format: {
+              message: "Please use `InitializedBy` enum to set the value.",
+            },
             target: target,
           });
           return;
@@ -1043,7 +1045,9 @@ export const $clientInitialization: ClientInitializationDecorator = (
           ) {
             reportDiagnostic(context.program, {
               code: "invalid-initialized-by",
-              format: { message: "Please use `InitializedBy` enum to set the value." },
+              format: {
+                message: "Please use `InitializedBy` enum to set the value.",
+              },
               target: target,
             });
             return;

packages/typespec-client-generator-core/src/interfaces.ts

@@ -160,12 +160,15 @@ export enum UsageFlags {
 
 /**
  * Flags used to indicate how a client is initialized.
- * `Default` means author doesn't set initialization way for the client. It is only for internal usage and not exposed in decorator.
- * `Individually` means the client is initialized individually.
- * `Parent` means the client is initialized by its parent.
+ *
+ * Note: `Default` and `None` are sentinel values (not bit flags) and should not be combined with other values.
+ * - `Default` (-1): Internal use only. Indicates no explicit initialization decorator was set.
+ * - `None` (0): Decorator value from TypeSpec. Indicates client constructor should be omitted (hand-written).
+ * - `Individually` and `Parent` are bit flags (1, 2) that can be combined using bitwise OR.
  */
 export enum InitializedByFlags {
-  Default = 0,
+  Default = -1,
+  None = 0,
   Individually = 1 << 0,
   Parent = 1 << 1,
 }

packages/typespec-client-generator-core/test/decorators/client-initialization.test.ts

@@ -729,3 +729,35 @@ it("wrong initializedBy value type", async () => {
     code: "invalid-argument",
   });
 });
+
+it("client initialized with None", async () => {
+  const { program } = await SimpleBaseTester.compile(
+    createClientCustomizationInput(
+      `
+      @service
+      namespace MyService;
+
+      op download(@path blobName: string): void;
+      `,
+      `
+      namespace MyCustomizations;
+
+      model MyClientInitialization {
+        blobName: string;
+      }
+
+      @@clientInitialization(MyService, {parameters: MyCustomizations.MyClientInitialization, initializedBy: InitializedBy.none});
+      `,
+    ),
+  );
+  const context = await createSdkContextForTester(program);
+  const sdkPackage = context.sdkPackage;
+  const client = sdkPackage.clients[0];
+  strictEqual(client.clientInitialization.initializedBy, InitializedByFlags.None);
+  strictEqual(client.clientInitialization.parameters.length, 2);
+  const endpoint = client.clientInitialization.parameters.find((x) => x.kind === "endpoint");
+  ok(endpoint);
+  const blobName = client.clientInitialization.parameters.find((x) => x.name === "blobName");
+  ok(blobName);
+  strictEqual(blobName.onClient, true);
+});

website/src/content/docs/docs/libraries/typespec-client-generator-core/reference/data-types.md

@@ -86,10 +86,11 @@ InitializedBy value.
 enum Azure.ClientGenerator.Core.InitializedBy
 ```
 
-| Name         | Value | Description                                       |
-| ------------ | ----- | ------------------------------------------------- |
-| individually | `1`   | The client could be initialized individually.     |
-| parent       | `2`   | The client could be initialized by parent client. |
+| Name         | Value | Description                                                   |
+| ------------ | ----- | ------------------------------------------------------------- |
+| none         |       | The client initialization should be omitted and hand-written. |
+| individually | `1`   | The client could be initialized individually.                 |
+| parent       | `2`   | The client could be initialized by parent client.             |
 
 ### `Usage` {#Azure.ClientGenerator.Core.Usage}