@wictorwilen/cocogen 1.0.0 → 1.0.11

package/dist/init/templates/ts/src/core/connectorCore.ts.ejs

@@ -0,0 +1,384 @@
+import type { ItemSource } from "../datasource/itemSource.js";
+
+type ProfileSourceOptions = {
+  webUrl: string;
+  displayName: string;
+  priority: "first" | "last";
+};
+
+export type ConnectorCoreOptions<Item> = {
+  graphBaseUrl: string;
+  contentCategory: string | null;
+  schemaPayload: unknown;
+  getAccessToken: () => Promise<string>;
+  getItemId: (item: Item) => string;
+  toExternalItem: (item: Item) => {
+    acl: Array<{ type: string; value: string; accessType: string }>;
+    properties: Record<string, unknown>;
+    content?: { type: string; value: string };
+  };
+  profileSource?: ProfileSourceOptions;
+};
+
+export type ProvisionOptions = {
+  connectionId: string;
+  connectionName: string;
+  connectionDescription: string;
+};
+
+export type IngestOptions<Item> = {
+  source: ItemSource;
+  connectionId: string;
+  dryRun?: boolean;
+  limit?: number;
+  verbose?: boolean;
+  toExternalItem: (item: Item) => unknown;
+};
+
+/**
+ * Reusable connector core for provisioning, ingestion, and deletion.
+ */
+export class ConnectorCore<Item> {
+  private readonly graphBaseUrl: string;
+  private readonly contentCategory: string | null;
+  private readonly schemaPayload: unknown;
+  private readonly getAccessToken: () => Promise<string>;
+  private readonly getItemId: (item: Item) => string;
+  private readonly toExternalItem: (item: Item) => {
+    acl: Array<{ type: string; value: string; accessType: string }>;
+    properties: Record<string, unknown>;
+    content?: { type: string; value: string };
+  };
+  private readonly profileSource?: ProfileSourceOptions;
+
+  constructor(options: ConnectorCoreOptions<Item>) {
+    this.graphBaseUrl = options.graphBaseUrl;
+    this.contentCategory = options.contentCategory;
+    this.schemaPayload = options.schemaPayload;
+    this.getAccessToken = options.getAccessToken;
+    this.getItemId = options.getItemId;
+    this.toExternalItem = options.toExternalItem;
+    this.profileSource = options.profileSource;
+  }
+
+  /**
+   * Ensure the external connection exists (create if missing).
+   */
+  async ensureConnection(options: ProvisionOptions): Promise<void> {
+    const payload: any = {
+      id: options.connectionId,
+      name: options.connectionName,
+      description: options.connectionDescription,
+    };
+
+    if (this.contentCategory) payload.contentCategory = this.contentCategory;
+
+    const createUrl = `${this.graphBaseUrl}/external/connections`;
+    const create = await this.graphRequest("POST", createUrl, payload);
+    if (!create.ok && create.status !== 409) {
+      const text = await create.text();
+      throw new Error(`Failed to create connection (HTTP ${create.status}): ${text}`);
+    }
+  }
+
+  /**
+   * Patch the external connection schema using the generated payload.
+   */
+  async patchSchema(connectionId: string): Promise<void> {
+    const schemaUrl = `${this.graphBaseUrl}/external/connections/${connectionId}/schema`;
+    const res = await this.graphRequest("PATCH", schemaUrl, this.schemaPayload);
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Failed to patch schema (HTTP ${res.status}): ${text}`);
+    }
+
+    await this.waitForSchemaReady(connectionId);
+  }
+
+  /**
+   * Provision connection + schema and (optionally) profile source.
+   */
+  async provision(options: ProvisionOptions): Promise<void> {
+    await this.ensureConnection(options);
+    await this.patchSchema(options.connectionId);
+    if (this.profileSource) {
+      await this.registerProfileSourceInternal(options.connectionId, this.profileSource);
+    }
+  }
+
+  /**
+   * Register the connection as a profile source (people connectors only).
+   */
+  async registerProfileSource(connectionId: string): Promise<void> {
+    if (!this.profileSource) {
+      throw new Error("Profile source settings are missing.");
+    }
+    await this.registerProfileSourceInternal(connectionId, this.profileSource);
+  }
+
+  /**
+   * Remove the connection from profile source registrations (people connectors only).
+   */
+  async unregisterProfileSource(connectionId: string): Promise<void> {
+    if (!this.profileSource) {
+      throw new Error("Profile source settings are missing.");
+    }
+    await this.unregisterProfileSourceInternal(connectionId);
+  }
+
+  /**
+   * Delete the external connection.
+   */
+  async deleteConnection(connectionId: string): Promise<void> {
+    if (this.profileSource) {
+      await this.unregisterProfileSourceInternal(connectionId);
+    }
+
+    const res = await this.graphRequest("DELETE", `${this.graphBaseUrl}/external/connections/${connectionId}`);
+    if (!res.ok && res.status !== 404) {
+      const text = await res.text();
+      throw new Error(`Failed to delete connection (HTTP ${res.status}): ${text}`);
+    }
+  }
+
+  /**
+   * Upsert a single item to Graph.
+   */
+  async putItem(connectionId: string, item: Item, verbose: boolean): Promise<void> {
+    const itemId = this.getItemId(item);
+    const url = `${this.graphBaseUrl}/external/connections/${connectionId}/items/${encodeURIComponent(itemId)}`;
+
+    const payload = this.toExternalItem(item);
+    if (verbose) {
+      console.log("verbose: PUT", url);
+      console.log("verbose: payload", JSON.stringify(payload, null, 2));
+    }
+
+    const res = await this.graphRequest("PUT", url, payload);
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Failed to ingest item '${itemId}' (HTTP ${res.status}): ${text}`);
+    }
+  }
+
+  /**
+   * Ingest items from a datasource.
+   */
+  async ingest(options: IngestOptions<Item>): Promise<void> {
+    let count = 0;
+    for await (const item of options.source.getItems()) {
+      if (options.limit && count >= options.limit) break;
+      const itemId = this.getItemId(item as Item);
+      if (!options.dryRun) {
+        console.log(`info: ingesting item ${count + 1} (id=${itemId})`);
+        try {
+          await this.putItem(options.connectionId, item as Item, Boolean(options.verbose));
+          console.log(`ok: ingested item ${count + 1} (id=${itemId})`);
+        } catch (error) {
+          console.error(`error: failed item ${count + 1} (id=${itemId})`);
+          throw error;
+        }
+      } else if (options.verbose) {
+        console.log(`verbose: DRY RUN item ${count + 1} (id=${itemId})`, JSON.stringify(options.toExternalItem(item as Item), null, 2));
+      }
+      count++;
+    }
+
+    console.log("ok: ingested " + count + " item(s)");
+  }
+
+  private async graphRequest(method: string, url: string, body?: unknown): Promise<Response> {
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+      const token = await this.getAccessToken();
+      const res = await fetch(url, {
+        method,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json",
+        },
+        body: body ? JSON.stringify(body) : undefined,
+      });
+
+      if (!shouldRetry(res.status) || attempt === MAX_RETRIES) {
+        return res;
+      }
+
+      const retryAfterMs = parseRetryAfter(res.headers.get("Retry-After"));
+      const delay = computeDelay(attempt, retryAfterMs);
+      console.warn(`warn: throttled (HTTP ${res.status}) for ${url}, retrying in ${delay}ms`);
+      await sleep(delay);
+    }
+
+    throw new Error("Failed to send request after retries.");
+  }
+
+  private async listProfilePropertySettings(): Promise<Array<{ id: string; prioritizedSourceUrls: string[] }>> {
+    const res = await this.graphRequest("GET", `${this.graphBaseUrl}/admin/people/profilePropertySettings`);
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Failed to list profile property settings (HTTP ${res.status}): ${text}`);
+    }
+    const json = (await res.json()) as { value?: Array<{ id?: string; prioritizedSourceUrls?: string[] }> };
+    return (json.value ?? [])
+      .filter((entry) => typeof entry.id === "string")
+      .map((entry) => ({
+        id: entry.id as string,
+        prioritizedSourceUrls: Array.isArray(entry.prioritizedSourceUrls) ? entry.prioritizedSourceUrls : [],
+      }));
+  }
+
+  private async listProfileSources(): Promise<Array<{ sourceId: string }>> {
+    const res = await this.graphRequest("GET", `${this.graphBaseUrl}/admin/people/profileSources`);
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Failed to list profile sources (HTTP ${res.status}): ${text}`);
+    }
+    const json = (await res.json()) as { value?: Array<{ sourceId?: string }> };
+    return (json.value ?? [])
+      .filter((entry) => typeof entry.sourceId === "string")
+      .map((entry) => ({ sourceId: entry.sourceId as string }));
+  }
+
+  private async registerProfileSourceInternal(connectionId: string, profile: ProfileSourceOptions): Promise<void> {
+    const sources = await this.listProfileSources();
+    if (sources.some((source) => source.sourceId === connectionId)) {
+      return;
+    }
+
+    const payload: any = {
+      sourceId: connectionId,
+      displayName: profile.displayName,
+      webUrl: profile.webUrl,
+    };
+
+    const create = await this.graphRequest("POST", `${this.graphBaseUrl}/admin/people/profileSources`, payload);
+    if (!create.ok && create.status !== 409) {
+      const text = await create.text();
+      throw new Error(`Failed to register profile source (HTTP ${create.status}): ${text}`);
+    }
+
+    const sourceUrl = `${this.graphBaseUrl}/admin/people/profileSources(sourceId='${connectionId}')`;
+    const settings = await this.listProfilePropertySettings();
+    for (const setting of settings) {
+      const existing = this.uniqueUrls(setting.prioritizedSourceUrls).filter((value) => value !== sourceUrl);
+      const updated = profile.priority === "first"
+        ? this.uniqueUrls([sourceUrl, ...existing])
+        : this.uniqueUrls([...existing, sourceUrl]);
+      const res = await this.graphRequest(
+        "PATCH",
+        `${this.graphBaseUrl}/admin/people/profilePropertySettings/${setting.id}`,
+        {
+          "@odata.type": "#microsoft.graph.profilePropertySetting",
+          prioritizedSourceUrls: updated,
+        }
+      );
+      if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Failed to update profile property setting ${setting.id} (HTTP ${res.status}): ${text}`);
+      }
+    }
+  }
+
+  private async unregisterProfileSourceInternal(connectionId: string): Promise<void> {
+    const sourceUrl = `${this.graphBaseUrl}/admin/people/profileSources(sourceId='${connectionId}')`;
+    const settings = await this.listProfilePropertySettings();
+    for (const setting of settings) {
+      const updated = this.uniqueUrls(setting.prioritizedSourceUrls).filter((value) => value !== sourceUrl);
+      const res = await this.graphRequest(
+        "PATCH",
+        `${this.graphBaseUrl}/admin/people/profilePropertySettings/${setting.id}`,
+        {
+          "@odata.type": "#microsoft.graph.profilePropertySetting",
+          prioritizedSourceUrls: updated,
+        }
+      );
+      if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Failed to update profile property setting ${setting.id} (HTTP ${res.status}): ${text}`);
+      }
+    }
+
+    const res = await this.graphRequest(
+      "DELETE",
+      `${this.graphBaseUrl}/admin/people/profileSources(sourceId='${connectionId}')`
+    );
+    if (!res.ok && res.status !== 404) {
+      const text = await res.text();
+      throw new Error(`Failed to delete profile source (HTTP ${res.status}): ${text}`);
+    }
+  }
+
+  private uniqueUrls(values: string[]): string[] {
+    const seen = new Set<string>();
+    const result: string[] = [];
+    for (const value of values) {
+      if (!value) continue;
+      if (seen.has(value)) continue;
+      seen.add(value);
+      result.push(value);
+    }
+    return result;
+  }
+
+  private async waitForSchemaReady(connectionId: string): Promise<void> {
+    const schemaUrl = `${this.graphBaseUrl}/external/connections/${connectionId}/schema`;
+    console.log("info: waiting for schema provisioning...");
+    for (let attempt = 0; attempt < SCHEMA_POLL_MAX_ATTEMPTS; attempt++) {
+      const res = await this.graphRequest("GET", schemaUrl);
+      if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Failed to read schema status (HTTP ${res.status}): ${text}`);
+      }
+      const json = (await res.json()) as { status?: { state?: string } | string };
+      const state = typeof json.status === "string" ? json.status : json.status?.state;
+      if (!state) return;
+      const normalized = state.toLowerCase();
+      if (SCHEMA_READY_STATES.has(normalized)) return;
+      if (!SCHEMA_PENDING_STATES.has(normalized)) {
+        throw new Error(`Schema provisioning failed with status '${state}'.`);
+      }
+      console.log(`info: schema status '${state}' (${attempt + 1}/${SCHEMA_POLL_MAX_ATTEMPTS})`);
+      await sleep(SCHEMA_POLL_DELAY_MS);
+    }
+
+    throw new Error("Schema provisioning timed out.");
+  }
+}
+
+const MAX_RETRIES = 6;
+const BASE_DELAY_MS = 1000;
+const MAX_DELAY_MS = 30000;
+const SCHEMA_POLL_MAX_ATTEMPTS = 12;
+const SCHEMA_POLL_DELAY_MS = 30000;
+const SCHEMA_READY_STATES = new Set(["completed", "ready", "succeeded", "success"]);
+const SCHEMA_PENDING_STATES = new Set(["inprogress", "pending", "running", "updating"]);
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function parseRetryAfter(value: string | null): number | null {
+  if (!value) return null;
+  const seconds = Number(value);
+  if (!Number.isNaN(seconds) && Number.isFinite(seconds)) {
+    return Math.max(0, seconds * 1000);
+  }
+
+  const dateMs = Date.parse(value);
+  if (!Number.isNaN(dateMs)) {
+    return Math.max(0, dateMs - Date.now());
+  }
+
+  return null;
+}
+
+function computeDelay(attempt: number, retryAfter: number | null): number {
+  if (retryAfter !== null) return Math.min(retryAfter, MAX_DELAY_MS);
+  const exp = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * Math.pow(2, attempt));
+  const jitter = Math.floor(Math.random() * 250);
+  return Math.min(MAX_DELAY_MS, exp + jitter);
+}
+
+function shouldRetry(status: number): boolean {
+  return status === 429 || status === 503 || status === 504;
+}

package/dist/init/templates/ts/src/datasource/csvItemSource.ts.ejs

@@ -1,15 +1,23 @@
+/**
+ * Default CSV datasource implementation.
+ */
 import { createReadStream } from "node:fs";
 import { parse } from "csv-parse";
 
-import type { Item } from "../schema/model.js";
+import type { <%= itemTypeName %> } from "../<%= schemaFolderName %>/model.js";
 import type { ItemSource } from "./itemSource.js";
-import { fromCsvRow } from "../schema/fromCsvRow.js";
+import { fromCsvRow } from "../<%= schemaFolderName %>/fromCsvRow.js";
 
-// CSV-based datasource (default). Replace with your own ItemSource as needed.
+/**
+ * CSV-based datasource (default). Replace with your own ItemSource as needed.
+ */
 export class CsvItemSource implements ItemSource {
   constructor(private readonly filePath: string) {}
 
-  async *getItems(): AsyncIterable<Item> {
+  /**
+   * Stream items from the CSV file and map each row to the schema model.
+   */
+  async *getItems(): AsyncIterable<<%= itemTypeName %>> {
     const parser = parse({
       columns: true,
       skip_empty_lines: true,

package/dist/init/templates/ts/src/datasource/itemSource.ts.ejs

@@ -1,8 +1,15 @@
-import type { Item } from "../schema/model.js";
+/**
+ * Datasource contract for producing items to ingest.
+ */
+import type { <%= itemTypeName %> } from "../<%= schemaFolderName %>/model.js";
 
-// Contract for any datasource that yields Items for ingestion.
-// Implement this interface to swap CSV for an API, database, or other system.
+/**
+ * Contract for any datasource that yields items for ingestion.
+ * Implement this interface to swap CSV for an API, database, or other system.
+ */
 export interface ItemSource {
-  // Return items as an async iterable (streaming preferred).
-  getItems(): AsyncIterable<Item>;
+  /**
+   * Return items as an async iterable (streaming preferred).
+   */
+  getItems(): AsyncIterable<<%= itemTypeName %>>;
 }

package/dist/init/templates/ts/src/generated/constants.ts.ejs

@@ -1,10 +1,26 @@
+/**
+ * Schema and connection constants derived from TypeSpec.
+ * This file is generated; edit TypeSpec or rerun cocogen to update.
+ */
 export const graphApiVersion = <%= JSON.stringify(graphApiVersion) %> as const;
+/** Graph API version used by the connector. */
 export const contentCategory: string | null = <%= JSON.stringify(contentCategory) %>;
+/** Optional content category for the connection. */
+export const connectionName: string | null = <%= JSON.stringify(connectionName) %>;
+/** Default connection name, if provided in TypeSpec. */
 export const connectionId: string | null = <%= JSON.stringify(connectionId) %>;
+/** Default connection ID, if provided in TypeSpec. */
 export const connectionDescription: string | null = <%= JSON.stringify(connectionDescription) %>;
+/** Default connection description, if provided in TypeSpec. */
 export const profileSourceWebUrl: string | null = <%= JSON.stringify(profileSourceWebUrl) %>;
+/** Default profile source URL for people connectors. */
 export const profileSourceDisplayName: string | null = <%= JSON.stringify(profileSourceDisplayName) %>;
+/** Default profile source display name for people connectors. */
 export const profileSourcePriority: "first" | "last" | null = <%= JSON.stringify(profileSourcePriority) %>;
+/** Default profile source priority for people connectors. */
 export const itemTypeName = <%= JSON.stringify(itemTypeName) %> as const;
+/** Item model name declared in TypeSpec. */
 export const idPropertyName = <%= JSON.stringify(idPropertyName) %> as const;
+/** Property name used as the external item ID. */
 export const contentPropertyName: string | null = <%= JSON.stringify(contentPropertyName) %>;
+/** Optional content property for full-text indexing. */

package/dist/init/templates/ts/src/generated/csv.ts.ejs

@@ -1,8 +1,13 @@
+/**
+ * CSV parsing helpers used by generated transforms.
+ */
+/** Parse any CSV cell value into a string (empty when nullish). */
 function parseString(value: unknown): string {
   if (value === undefined || value === null) return "";
   return String(value);
 }
 
+/** Parse a numeric CSV cell into a number (defaults to 0). */
 function parseNumber(value: unknown): number {
   const text = parseString(value).trim();
   if (!text) return 0;
@@ -10,25 +15,30 @@ function parseNumber(value: unknown): number {
   return Number.isFinite(numberValue) ? numberValue : 0;
 }
 
+/** Parse a boolean-ish CSV cell into a boolean. */
 function parseBoolean(value: unknown): boolean {
   const text = parseString(value).trim().toLowerCase();
   return text === "true" || text === "1" || text === "yes";
 }
 
+/** Split a delimited CSV cell into an array of strings. */
 function splitCollection(value: unknown): string[] {
   const text = parseString(value).trim();
   if (!text) return [];
   return text.split(/\s*[;,|]\s*/).map((s) => s.trim()).filter(Boolean);
 }
 
+/** Parse a string collection from a CSV cell. */
 function parseStringCollection(value: unknown): string[] {
   return splitCollection(value);
 }
 
+/** Parse a number collection from a CSV cell. */
 function parseNumberCollection(value: unknown): number[] {
   return splitCollection(value).map((s) => parseNumber(s));
 }
 
+/** Read a value from a row using the first matching header. */
 function readSourceValue(row: Record<string, unknown>, headers: string[]): unknown {
   if (headers.length === 0) return "";
   return row[headers[0]];

package/dist/init/templates/ts/src/generated/fromCsvRow.ts.ejs

@@ -1,43 +1,18 @@
-import type { Item } from "./model.js";
-import {
-  parseBoolean,
-  parseNumber,
-  parseNumberCollection,
-  parseString,
-  parseStringCollection,
-  readSourceValue
-} from "../datasource/csv.js";
-<% if (propertyTransforms.length > 0) { -%>
-import {
-<% for (const prop of propertyTransforms) { -%>
-  transform<%= prop.transformName %>,
-<% } -%>
-} from "./propertyTransforms.js";
-<% } -%>
-<% if (hasPersonEntities) { -%>
-import { buildPersonEntityDefault, buildPersonEntityDefaultCollection } from "./personEntityDefaults.js";
-import { transformPersonEntity, transformPersonEntityCollection } from "./personEntityOverrides.js";
-<% } -%>
+/**
+ * Map raw CSV rows into the schema model.
+ */
+import type { <%= itemTypeName %> } from "./model.js";
+import { PropertyTransform } from "./propertyTransform.js";
+
+const transforms = new PropertyTransform();
 
-export function fromCsvRow(row: Record<string, unknown>): Item {
+/**
+ * Convert a CSV row into the schema model using generated transforms.
+ */
+export function fromCsvRow(row: Record<string, unknown>): <%= itemTypeName %> {
   return {
 <% for (const prop of properties) { -%>
-  <% if (prop.expression) { -%>
-    <%= prop.name %>: <%= prop.isCollection ? "transformPersonEntityCollection" : "transformPersonEntity" %>(
-      <%= JSON.stringify(prop.name) %>,
-      row,
-      <%= prop.isCollection ? "buildPersonEntityDefaultCollection" : "buildPersonEntityDefault" %>(
-        <%= JSON.stringify(prop.name) %>,
-        row
-      )
-    ),
-  <% } else { -%>
-    <% if (prop.isExplicitSource) { -%>
-    <%= prop.name %>: transform<%= prop.transformName %>(readSourceValue(row, <%= JSON.stringify(prop.csvHeaders) %>)),
-    <% } else { -%>
-    <%= prop.name %>: transform<%= prop.transformName %>(row),
-    <% } -%>
-  <% } -%>
+    <%= prop.name %>: transforms.transformProperty<%= prop.tsType ? `<${prop.tsType}>` : "" %>(<%= JSON.stringify(prop.name) %>, row),
 <% } -%>
   };
 }

package/dist/init/templates/ts/src/generated/index.ts.ejs

@@ -1,3 +1,6 @@
+/**
+ * Barrel exports for generated schema helpers.
+ */
 export * from "./constants.js";
 export * from "./model.js";
 export * from "./schemaPayload.js";

package/dist/init/templates/ts/src/generated/itemPayload.ts.ejs

@@ -1,11 +1,20 @@
-import type { Item } from "./model.js";
+/**
+ * Build ExternalItem payloads for Graph ingestion.
+ */
+import type { <%= itemTypeName %> } from "./model.js";
 import { contentPropertyName, idPropertyName } from "./constants.js";
 
-export function getItemId(item: Item): string {
+/**
+ * Resolve the external item ID from the schema model.
+ */
+export function getItemId(item: <%= itemTypeName %>): string {
   return String((item as any)[idPropertyName] ?? "");
 }
 
-export function toExternalItem(item: Item): {
+/**
+ * Convert a schema model instance into a Graph ExternalItem payload.
+ */
+export function toExternalItem(item: <%= itemTypeName %>): {
   acl: Array<{ type: string; value: string; accessType: string }>;
   properties: Record<string, unknown>;
   content?: { type: string; value: string };

package/dist/init/templates/ts/src/generated/model.ts.ejs

@@ -1,16 +1,8 @@
-<% if (itemTypeName === "Item") { -%>
-export type Item = {
-<% for (const prop of properties) { -%>
-  <%= prop.name %>: <%= prop.tsType %>;
-<% } -%>
-};
-<% } else { -%>
-
+/**
+ * TypeScript representation of the external item schema.
+ */
 export type <%= itemTypeName %> = {
 <% for (const prop of properties) { -%>
   <%= prop.name %>: <%= prop.tsType %>;
 <% } -%>
 };
-
-export type Item = <%= itemTypeName %>;
-<% } -%>

package/dist/init/templates/ts/src/generated/propertyTransformBase.ts.ejs

@@ -0,0 +1,40 @@
+/**
+ * Generated property transforms derived from TypeSpec.
+ * Regenerated on every cocogen update.
+ */
+
+import {
+  parseBoolean,
+  parseNumber,
+  parseNumberCollection,
+  parseString,
+  parseStringCollection,
+  readSourceValue
+} from "../datasource/csv.js";
+
+/**
+ * Base class for CSV-to-model transforms.
+ */
+export abstract class PropertyTransformBase {
+  /**
+   * Transform a property by name using the generated transform methods.
+   */
+  public transformProperty<T>(name: string, row: Record<string, unknown>): T {
+    switch (name) {
+<% for (const prop of properties) { -%>
+      case <%= JSON.stringify(prop.name) %>:
+        return this.transform<%= prop.transformName %>(row) as T;
+<% } -%>
+      default:
+        throw new Error(`Unknown property '${name}'.`);
+    }
+  }
+
+<% for (const prop of properties) { -%>
+  /** Transform the <%= prop.name %> property from a CSV row. */
+  protected transform<%= prop.transformName %>(row: Record<string, unknown>): <%= prop.tsType %> {
+    return <%- prop.expression %>;
+  }
+
+<% } -%>
+}

package/dist/init/templates/ts/src/generated/schemaPayload.ts.ejs

@@ -1 +1,4 @@
+/**
+ * Graph schema payload derived from the TypeSpec model.
+ */
 export const schemaPayload = <%- schemaPayloadJson %> as const;

package/dist/init/templates/ts/src/index.ts.ejs

@@ -1 +1,4 @@
-export * from "./schema/index.js";
+/**
+ * Re-export generated schema helpers for downstream imports.
+ */
+export * from "./<%= schemaFolderName %>/index.js";