feat: add bytes support across generators and integrations (#220)

* Implement bytes

* Integration tests

* Update docs

* Add changeset

Author: kafkas

.changeset/bright-squids-care.md

@@ -0,0 +1,9 @@
+---
+'typesync-cli': minor
+---
+
+Add full Firestore `bytes` support across Typesync.
+
+- support `bytes` in schema definitions, schema conversion, validation, and Zod generation
+- generate the correct platform-specific bytes types for TypeScript, Python, Swift, and Firestore Rules
+- add emulator-backed integration coverage for TypeScript, Python, and Swift bytes round-trips

docs/schema/types.mdx

@@ -263,6 +263,39 @@ function isValidExample(data) {
 
 </CodeGroup>
 
+## `bytes`
+
+Represents a Firestore bytes value.
+
+<CodeGroup>
+
+```yaml definition.yml
+Example:
+  model: alias
+  type: bytes
+```
+
+```ts models.ts
+// Firebase Web targets emit firestore.Bytes; React Native Firebase emits firestore.Blob.
+export type Example = Buffer;
+```
+
+```swift models.swift
+typealias Example = Data
+```
+
+```python models.py
+Example = bytes
+```
+
+```javascript firestore.rules
+function isValidExample(data) {
+  return (data is bytes);
+}
+```
+
+</CodeGroup>
+
 ## `literal`
 
 Represents a literal type.

scripts/integration-test.ts

@@ -39,6 +39,26 @@ interface PlatformConfig {
   generatedDir: string;
   generatedExtension: string;
   generate: (definitionPath: string, outFile: string) => Promise<void>;
+  /**
+   * Optional follow-up generation passes. Used by TypeScript to additionally
+   * emit code against alternative SDK targets (e.g. the web SDK) so that
+   * cross-target features like the `bytes` primitive can be round-tripped
+   * with each target's native representation.
+   */
+  extraGenerations?: {
+    /**
+     * Subdirectory under `generatedDir` that the extra pass writes to. The
+     * platform's `tsconfig.json` / `Package.swift` etc. must already include
+     * files in this directory.
+     */
+    subdir: string;
+    /**
+     * Restricts the pass to a subset of fixtures (matched by basename, e.g.
+     * `'secrets'`). Omit to apply to every fixture.
+     */
+    onlyFixtures?: string[];
+    generate: (definitionPath: string, outFile: string) => Promise<void>;
+  }[];
   runs: { description: string; cwd: string; cmd: string; args: string[]; underEmulator: boolean }[];
 }
 
@@ -94,6 +114,30 @@ const PLATFORMS: Record<Platform, PlatformConfig> = {
         objectTypeFormat: 'interface',
       });
     },
+    // The `bytes` scenario is the only place where the wire-level
+    // representation differs across TS targets (Buffer vs firestore.Bytes
+    // vs firestore.Blob), so we emit it against the web SDK in addition
+    // to the admin SDK. The admin pass above writes `generated/secrets.ts`;
+    // this pass writes `generated/web/secrets.ts`, which is imported by
+    // the dedicated `secrets.web.test.ts` round-trip suite. The
+    // react-native-firebase target is verified by the unit/snapshot tests
+    // under `src/renderers/ts/__tests__/`; we don't run it here because
+    // `@react-native-firebase/firestore` is RN-runtime-only and cannot
+    // execute under Node.
+    extraGenerations: [
+      {
+        subdir: 'web',
+        onlyFixtures: ['secrets'],
+        async generate(definition, outFile) {
+          await typesync.generateTs({
+            definition,
+            outFile,
+            target: 'firebase@10',
+            objectTypeFormat: 'interface',
+          });
+        },
+      },
+    ],
     runs: [
       {
         description: 'tsc --noEmit (compile-time check)',
@@ -129,21 +173,35 @@ function listSchemaFixtures(): { path: string; name: string }[] {
 
 function clearGeneratedDir(generatedDir: string, extension: string): void {
   if (!existsSync(generatedDir)) return;
-  for (const entry of readdirSync(generatedDir)) {
-    if (entry.endsWith(extension)) {
-      rmSync(resolve(generatedDir, entry));
+  for (const entry of readdirSync(generatedDir, { withFileTypes: true })) {
+    const entryPath = resolve(generatedDir, entry.name);
+    if (entry.isDirectory()) {
+      clearGeneratedDir(entryPath, extension);
+      continue;
+    }
+    if (entry.name.endsWith(extension)) {
+      rmSync(entryPath);
     }
   }
 }
 
 async function generateAll(platform: Platform, config: PlatformConfig): Promise<void> {
   console.log(`\n[${platform}] generating fixtures…`);
   clearGeneratedDir(config.generatedDir, config.generatedExtension);
-  for (const fixture of listSchemaFixtures()) {
+  const fixtures = listSchemaFixtures();
+  for (const fixture of fixtures) {
     const outFile = resolve(config.generatedDir, `${fixture.name}${config.generatedExtension}`);
     await config.generate(fixture.path, outFile);
     console.log(`  → ${fixture.name} -> ${outFile}`);
   }
+  for (const extra of config.extraGenerations ?? []) {
+    const targets = extra.onlyFixtures ? fixtures.filter(f => extra.onlyFixtures!.includes(f.name)) : fixtures;
+    for (const fixture of targets) {
+      const outFile = resolve(config.generatedDir, extra.subdir, `${fixture.name}${config.generatedExtension}`);
+      await extra.generate(fixture.path, outFile);
+      console.log(`  → [${extra.subdir}] ${fixture.name} -> ${outFile}`);
+    }
+  }
 }
 
 const FIREBASE_BIN = resolve(REPO_ROOT, 'node_modules/.bin/firebase');

src/converters/definition-to-schema.ts

@@ -20,6 +20,8 @@ export function primitiveTypeToSchema(t: definition.types.Primitive): schema.typ
       return { type: 'double' };
     case 'timestamp':
       return { type: 'timestamp' };
+    case 'bytes':
+      return { type: 'bytes' };
     default:
       assertNever(t);
   }

src/core/zod/__tests__/build-zod-schema.test.ts

@@ -18,6 +18,7 @@ describe('buildZodSchemaMap()', () => {
       DoubleAlias: { model: 'alias', type: 'double' },
       BoolAlias: { model: 'alias', type: 'boolean' },
       TimestampAlias: { model: 'alias', type: 'timestamp' },
+      BytesAlias: { model: 'alias', type: 'bytes' },
       NilAlias: { model: 'alias', type: 'nil' },
       AnyAlias: { model: 'alias', type: 'any' },
       UnknownAlias: { model: 'alias', type: 'unknown' },
@@ -46,6 +47,12 @@ describe('buildZodSchemaMap()', () => {
       expect(getSchemaForModel(s, 'TimestampAlias').safeParse(new Date()).success).toBe(false);
       expect(getSchemaForModel(s, 'TimestampAlias').safeParse('2020-01-01').success).toBe(false);
     });
+
+    it('accepts only Buffer instances for bytes', () => {
+      expect(getSchemaForModel(s, 'BytesAlias').safeParse(Buffer.from('hello')).success).toBe(true);
+      expect(getSchemaForModel(s, 'BytesAlias').safeParse(new Uint8Array([1, 2, 3])).success).toBe(false);
+      expect(getSchemaForModel(s, 'BytesAlias').safeParse('hello').success).toBe(false);
+    });
   });
 
   describe('enums and literals', () => {

src/core/zod/_emitter.ts

@@ -23,6 +23,7 @@ export interface ZodEmitter<TOut> {
   int(): TOut;
   double(): TOut;
   timestamp(): TOut;
+  bytes(): TOut;
 
   stringLiteral(value: string): TOut;
   intLiteral(value: number): TOut;

src/core/zod/_runtime-emitter.ts

@@ -27,6 +27,7 @@ export function createRuntimeZodEmitter(registry: RuntimeZodRegistry): ZodEmitte
     int: () => z.number().int(),
     double: () => z.number(),
     timestamp: () => z.instanceof(Timestamp),
+    bytes: () => z.instanceof(Buffer),
 
     stringLiteral: value => z.literal(value),
     intLiteral: value => z.literal(value),

src/core/zod/build-zod-schema.ts

@@ -29,6 +29,8 @@ export function buildZodFromType<TOut>(type: schema.types.Type, emitter: ZodEmit
       return emitter.double();
     case 'timestamp':
       return emitter.timestamp();
+    case 'bytes':
+      return emitter.bytes();
     case 'string-literal':
       return emitter.stringLiteral(type.value);
     case 'int-literal':

src/definition/_guards.ts

@@ -12,6 +12,7 @@ export function isPrimitiveType(candidate: unknown): candidate is types.Primitiv
     case 'int':
     case 'double':
     case 'timestamp':
+    case 'bytes':
       return true;
     default:
       assertNeverNoThrow(c);

src/definition/impl/__tests__/consistent.ts

@@ -8,6 +8,7 @@ import {
   anyType,
   booleanLiteralType,
   booleanType,
+  bytesType,
   definition,
   discriminatedUnionType,
   documentModel,
@@ -86,6 +87,12 @@ type IsExact<T, U> = [Required<T>] extends [Required<U>] ? ([Required<U>] extend
   assertEmpty<IsExact<DeclaredType, InferredType>>(true);
 })();
 
+(() => {
+  type DeclaredType = types.Bytes;
+  type InferredType = z.infer<typeof bytesType>;
+  assertEmpty<IsExact<DeclaredType, InferredType>>(true);
+})();
+
 (() => {
   type DeclaredType = types.Primitive;
   type InferredType = z.infer<typeof primitiveType>;