feat!: add Swift @DocumentID generation and Swift field renaming (#214)

* Implement document id field and platform options

* Tests

* Improved tests

Author: kafkas

.changeset/swift-document-id-and-field-rename.md

@@ -0,0 +1,14 @@
+---
+'typesync-cli': minor
+---
+
+Swift: auto-emit `@DocumentID var id: String?` on every generated document-model struct, plus two new schema-level overrides for the Swift generator.
+
+- The Firebase iOS SDK populates `@DocumentID` properties from the document path (and excludes them from the encoded body), so generated structs are now drop-in usable with `getDocument(as:)` / `setData(from:)` without manual edits.
+- New per-document-model option `swift.documentIdProperty.name` lets you rename the auto-generated `@DocumentID` property (default: `id`). Set this when your document body already has a field whose Firestore key is `id`, since the Firebase iOS SDK refuses to decode a document where the `@DocumentID` property name matches a body wire key.
+- New per-field option `swift.name` lets you rename a body property in the generated Swift output without changing its Firestore wire key. Useful for dodging Swift keywords or for ergonomics. The renderer routes the original Firestore key through a generated `CodingKeys` enum.
+- The Swift generator now throws when (a) a document model has a body field whose Firestore key matches the `@DocumentID` property name (rename one or the other via the options above), or (b) two body fields resolve to the same Swift property name. Both errors include the offending field names and a concrete remediation.
+
+This is a behavior change for Swift consumers: every generated document struct gains an `id: String?` property and an `import FirebaseFirestore` statement. Schemas with a body-side `id` field on a document model must opt in to a non-`id` `@DocumentID` property name via `swift: { documentIdProperty: { name: 'documentId' } }` (or similar) on the document model to keep generating successfully.
+
+The new options are structured as per-platform blocks (`swift: { ... }`) so future generators (Python, TypeScript, etc.) can layer in their own field-level and model-level overrides without further breaking changes.

schema.local.json

@@ -94,6 +94,7 @@ export function fieldToSchema(fieldName: string, field: definition.types.ObjectF
     readonly: !!field.readonly,
     docs: field.docs ?? null,
     name: fieldName,
+    ...(field.swift !== undefined ? { platformOptions: { swift: { ...field.swift } } } : {}),
   };
 }
 

src/converters/definition-to-schema.ts

@@ -169,6 +169,19 @@ export const type: z.ZodType<types.Type> = z.lazy(() =>
     .describe('Any valid type.')
 );
 
+export const swiftFieldOptions = z
+  .object({
+    name: z
+      .string()
+      .min(1)
+      .optional()
+      .describe(
+        "Overrides the Swift property name used to decode this field. Encoding is unaffected: the field is still serialized to Firestore under the schema's field name (the Swift renderer routes the original name through `CodingKeys`). Useful when the schema name collides with a Swift keyword or with an auto-generated property such as `@DocumentID var id`."
+      ),
+  })
+  .strict()
+  .describe('Swift-specific overrides for an object field.');
+
 export const objectField = z
   .object({
     type: type,
@@ -180,6 +193,9 @@ export const objectField = z
         'Whether this field is read-only. Defaults to false. This information is used by the Security Rules generator when producing validators that detect whether a read-only field has been affected by a write.'
       ),
     docs: z.string().optional().describe('Optional documentation for the object field.'),
+    swift: swiftFieldOptions
+      .optional()
+      .describe('Per-platform overrides for the Swift generator. See `SwiftFieldOptions`.'),
   })
   .strict()
   .describe('An object field.');
@@ -193,6 +209,26 @@ export const aliasModel = z
   .strict()
   .describe('An alias model');
 
+export const swiftDocumentModelOptions = z
+  .object({
+    documentIdProperty: z
+      .object({
+        name: z
+          .string()
+          .min(1)
+          .describe(
+            "The Swift property name for the auto-generated `@DocumentID`-annotated field. Defaults to `id`. Set this to a non-`id` value (e.g. `documentId`) when the schema's document body has a field whose Firestore key is also `id`, since the Firebase iOS SDK refuses to decode a document where the `@DocumentID` property name matches an existing body field's key."
+          ),
+      })
+      .strict()
+      .optional()
+      .describe(
+        "Configuration for the auto-generated `@DocumentID`-annotated property that the Swift generator emits on every document-model struct. The Firebase iOS SDK populates this property from the document's path on read and excludes it from the encoded body on write."
+      ),
+  })
+  .strict()
+  .describe('Swift-specific overrides for a document model.');
+
 export const documentModel = z
   .object({
     model: z.literal('document').describe(`A literal field indicating that this is a 'document' model.`),
@@ -204,6 +240,9 @@ export const documentModel = z
       .describe(
         `An exact or generic path to the document. Must be a string consisting of path segments separated by a '/' (slash). Each segment can either be a literal ID or a generic ID of the collection or document. A literal ID is a plain string, such as 'users', while a generic ID must be enclosed in curly braces (e.g. '{userId}').`
       ),
+    swift: swiftDocumentModelOptions
+      .optional()
+      .describe('Per-platform overrides for the Swift generator. See `SwiftDocumentModelOptions`.'),
   })
   .strict()
   .describe('A document model.');

src/definition/impl/_zod-schemas.ts

@@ -11,6 +11,30 @@ export interface DocumentModel {
   docs?: string;
   type: types.Object;
   path: string;
+  swift?: SwiftDocumentModelOptions;
+}
+
+/**
+ * Swift-specific overrides for a document model. Only consumed by the Swift
+ * generator; ignored by every other generator.
+ */
+export interface SwiftDocumentModelOptions {
+  /**
+   * Configuration for the auto-generated `@DocumentID`-annotated property
+   * that the Swift generator emits on every document model struct.
+   */
+  documentIdProperty?: {
+    /**
+     * The Swift property name for the auto-generated `@DocumentID` field.
+     * Defaults to `id`.
+     *
+     * Set this to a non-`id` value (e.g. `documentId`) when the schema's
+     * document body already has a field whose Firestore key is `id`, since
+     * the Firebase iOS SDK refuses to decode a document where the
+     * `@DocumentID` property name matches an existing body field's key.
+     */
+    name: string;
+  };
 }
 
 export type Model = AliasModel | DocumentModel;

src/definition/impl/impl.ts

@@ -81,6 +81,23 @@ export interface ObjectField {
   optional?: boolean;
   readonly?: boolean;
   docs?: string;
+  swift?: SwiftFieldOptions;
+}
+
+/**
+ * Swift-specific overrides for an object field. Only consumed by the Swift
+ * generator; ignored by every other generator.
+ */
+export interface SwiftFieldOptions {
+  /**
+   * Overrides the Swift property name used to decode this field.
+   *
+   * Encoding is unaffected: the field is still serialized to Firestore under
+   * the schema's field name (the Swift renderer routes the original name
+   * through `CodingKeys`). Useful when the schema name collides with a Swift
+   * keyword or with an auto-generated property such as `@DocumentID var id`.
+   */
+  name?: string;
 }
 
 export interface DiscriminatedUnion {

src/definition/types/_types.ts

@@ -11,3 +11,33 @@ export class MixedEnumValueTypesNotSupportedError extends SwiftGeneratorError {
     );
   }
 }
+
+export class SwiftPropertyNameCollisionError extends SwiftGeneratorError {
+  /**
+   * `sources` describes where each colliding name came from. Body fields are
+   * cited by their Firestore key (the schema field name); the auto-generated
+   * `@DocumentID` property is cited as the literal string `@DocumentID`.
+   */
+  public constructor(modelName: string, propertyName: string, sources: readonly string[]) {
+    const involvesDocumentId = sources.includes('@DocumentID');
+    const fieldSources = sources.filter(s => s !== '@DocumentID');
+    const formattedSources = sources.map(n => (n === '@DocumentID' ? n : `'${n}'`)).join(', ');
+    const remediation = involvesDocumentId
+      ? `Either rename the auto-generated \`@DocumentID\` property by adding \`swift: { documentIdProperty: { name: '<unique-name>' } }\` to the document model, or rename the conflicting field${fieldSources.length > 1 ? 's' : ''} by setting \`swift: { name: '<unique-name>' }\` on ${fieldSources.length > 1 ? 'one of them' : 'it'}.`
+      : `Disambiguate one of them by setting \`swift: { name: '<unique-name>' }\` on the field in your schema definition.`;
+    const causeBlurb = involvesDocumentId
+      ? `In the generated Swift struct, ${fieldSources.map(n => `field '${n}'`).join(' and ')} would have the same property name as the auto-generated \`@DocumentID\` property, which Swift does not allow. `
+      : '';
+    super(
+      `Two or more properties on model '${modelName}' resolve to the same Swift property name '${propertyName}'. Conflicting source(s): ${formattedSources}. ${causeBlurb}${remediation}`
+    );
+  }
+}
+
+export class SwiftDocumentIdPropertyCollidesWithFieldError extends SwiftGeneratorError {
+  public constructor(modelName: string, fieldName: string, documentIdPropertyName: string) {
+    super(
+      `Document model '${modelName}' declares a body field named '${fieldName}', whose Firestore key matches the auto-generated \`@DocumentID\` property name '${documentIdPropertyName}'. The Firebase iOS SDK refuses to decode such documents because the path-derived id and the body field would clash on the same wire key. Rename the \`@DocumentID\` property by adding \`swift: { documentIdProperty: { name: '<unique-name>' } }\` to the document model in your schema definition (e.g. \`name: 'documentId'\`). The body field then keeps its current Firestore key and Swift name.`
+    );
+  }
+}

src/errors/generator.ts

@@ -58,6 +58,7 @@ export function adjustSchemaForPython(prevSchema: schema.Schema): schema.python.
         optional: r.field.optional,
         readonly: r.field.readonly,
         type: r.flattenResult.flattenedType,
+        platformOptions: r.field.platformOptions,
       })),
       additionalFields: objectType.additionalFields,
     };

src/generators/python/_adjust-schema.ts

@@ -32,6 +32,7 @@ export function adjustSchemaForRules(prevSchema: schema.Schema): schema.rules.Sc
         optional: field.optional,
         readonly: field.readonly,
         type: flattenType(field.type),
+        platformOptions: field.platformOptions,
       })),
       additionalFields: objectType.additionalFields,
     };