feat!: Add array support and isolate fields

fwal · fwal · commit bd35fb880c50 · 2026-03-08T22:33:58.000+01:00
diff --git a/packages/admin/src/lib/firestore/converter.spec.ts b/packages/admin/src/lib/firestore/converter.spec.ts
@@ -143,7 +143,7 @@ describe('Firestore Converter', () => {
       const fakeFirestore = {} as unknown as Firestore;
       const result = toFirestoreDocumentData(
         fakeFirestore,
-        FirestoreSchema.ArrayUnion.values(['a', 'b'])
+        FirestoreSchema.ArrayUnion.make({ values: ['a', 'b'] })
       );
       expect(result).toStrictEqual(FieldValue.arrayUnion('a', 'b'));
     });
@@ -152,7 +152,7 @@ describe('Firestore Converter', () => {
       const fakeFirestore = {} as unknown as Firestore;
       const result = toFirestoreDocumentData(
         fakeFirestore,
-        FirestoreSchema.ArrayRemove.values(['a'])
+        FirestoreSchema.ArrayRemove.make({ values: ['a'] })
       );
       expect(result).toStrictEqual(FieldValue.arrayRemove('a'));
     });
diff --git a/packages/admin/src/lib/firestore/converter.ts b/packages/admin/src/lib/firestore/converter.ts
@@ -7,7 +7,7 @@ import {
   GeoPoint,
   Timestamp,
 } from 'firebase-admin/firestore';
-import { FirestoreSchema } from 'effect-firebase';
+import { FirestoreSchema, FirestoreField } from 'effect-firebase';
 
 export const toFirestoreDocumentData = (
   db: Firestore,
@@ -35,13 +35,13 @@ export const toFirestoreDocumentData = (
   if (data instanceof FirestoreSchema.ServerTimestamp) {
     return FieldValue.serverTimestamp();
   }
-  if (data instanceof FirestoreSchema.Delete) {
+  if (data instanceof FirestoreField.Delete) {
     return FieldValue.delete();
   }
-  if (data instanceof FirestoreSchema.ArrayUnion) {
+  if (data instanceof FirestoreField.ArrayUnion) {
     return FieldValue.arrayUnion(...data.values);
   }
-  if (data instanceof FirestoreSchema.ArrayRemove) {
+  if (data instanceof FirestoreField.ArrayRemove) {
     return FieldValue.arrayRemove(...data.values);
   }
   if (Array.isArray(data)) {
diff --git a/packages/client/src/lib/firestore/converter.ts b/packages/client/src/lib/firestore/converter.ts
@@ -12,7 +12,7 @@ import {
   serverTimestamp,
   Timestamp,
 } from 'firebase/firestore';
-import { FirestoreSchema } from 'effect-firebase';
+import { FirestoreSchema, FirestoreField } from 'effect-firebase';
 
 export const toFirestoreDocumentData = (
   db: Firestore,
@@ -40,13 +40,13 @@ export const toFirestoreDocumentData = (
   if (data instanceof FirestoreSchema.ServerTimestamp) {
     return serverTimestamp();
   }
-  if (data instanceof FirestoreSchema.Delete) {
+  if (data instanceof FirestoreField.Delete) {
     return deleteField();
   }
-  if (data instanceof FirestoreSchema.ArrayUnion) {
+  if (data instanceof FirestoreField.ArrayUnion) {
     return arrayUnion(...data.values);
   }
-  if (data instanceof FirestoreSchema.ArrayRemove) {
+  if (data instanceof FirestoreField.ArrayRemove) {
     return arrayRemove(...data.values);
   }
   if (Array.isArray(data)) {
diff --git a/packages/effect-firebase/src/index.ts b/packages/effect-firebase/src/index.ts
@@ -1,4 +1,5 @@
 export * as FirestoreSchema from './lib/firestore/schema/schema.js';
+export * as FirestoreField from './lib/firestore/fields/fields.js';
 export * from './lib/firestore/firestore-service.js';
 export * from './lib/firestore/errors.js';
 export * from './lib/firestore/snapshot.js';
diff --git a/packages/effect-firebase/src/lib/firestore/fields/array.ts b/packages/effect-firebase/src/lib/firestore/fields/array.ts
@@ -0,0 +1,29 @@
+import { Schema } from 'effect';
+
+/**
+ * Represents an arrayUnion operation. This will add elements to an array field.
+ * Only valid in the `update` variant — use `WithArraySentinels` to add support to a field.
+ */
+export class ArrayUnion {
+  constructor(public readonly values: readonly unknown[]) {}
+}
+export const ArrayUnionInstance = Schema.instanceOf(ArrayUnion);
+
+/**
+ * Represents an arrayRemove operation. This will remove elements from an array field.
+ * Only valid in the `update` variant — use `WithArraySentinels` to add support to a field.
+ */
+export class ArrayRemove {
+  constructor(public readonly values: readonly unknown[]) {}
+}
+
+export const ArrayRemoveInstance = Schema.instanceOf(ArrayRemove);
+
+/** Add elements to an array field. */
+export const arrayUnion =
+  /** Add elements to an array field. */
+  (values: readonly unknown[]) => new ArrayUnion(values);
+
+/** Remove elements from an array field. */
+export const arrayRemove = (values: readonly unknown[]) =>
+  new ArrayRemove(values);
diff --git a/packages/effect-firebase/src/lib/firestore/fields/delete.ts b/packages/effect-firebase/src/lib/firestore/fields/delete.ts
@@ -0,0 +1,13 @@
+import { Schema } from 'effect';
+
+/**
+ * Represents a delete operation. This will remove the field from the document.
+ */
+export class Delete {}
+export const DeleteInstance = Schema.instanceOf(Delete);
+
+const _delete = () => new Delete();
+export {
+  /** Delete the field, removing it from the document. */
+  _delete as delete,
+};
diff --git a/packages/effect-firebase/src/lib/firestore/fields/fields.ts b/packages/effect-firebase/src/lib/firestore/fields/fields.ts
@@ -0,0 +1,2 @@
+export * from './delete.js';
+export * from './array.js';
diff --git a/packages/effect-firebase/src/lib/firestore/model/array.spec.ts b/packages/effect-firebase/src/lib/firestore/model/array.spec.ts
@@ -2,7 +2,12 @@ import { Schema } from 'effect';
 import { describe, expect, it } from 'vitest';
 import { Class } from './core.js';
 import { WithArrayFields, Array } from './array.js';
-import { ArrayUnion, ArrayRemove } from '../schema/fields.js';
+import {
+  ArrayUnion,
+  ArrayRemove,
+  arrayUnion,
+  arrayRemove,
+} from '../fields/array.js';
 
 describe('WithArrayFields', () => {
   class TestModel extends Class<TestModel>('TestModel')({
@@ -39,7 +44,7 @@ describe('WithArrayFields', () => {
     it('should accept an ArrayUnion sentinel', () => {
       const result = Schema.decodeUnknownSync(TestModel.update)({
         name: 'Post',
-        tags: ArrayUnion.values(['c', 'd']),
+        tags: arrayUnion(['c', 'd']),
       });
       expect(result.tags).toBeInstanceOf(ArrayUnion);
       expect(result.tags.values).toEqual(['c', 'd']);
@@ -48,7 +53,7 @@ describe('WithArrayFields', () => {
     it('should accept an ArrayRemove sentinel', () => {
       const result = Schema.decodeUnknownSync(TestModel.update)({
         name: 'Post',
-        tags: ArrayRemove.values(['a']),
+        tags: arrayRemove(['a']),
       });
       expect(result.tags).toBeInstanceOf(ArrayRemove);
       expect(result.tags.values).toEqual(['a']);
@@ -57,7 +62,7 @@ describe('WithArrayFields', () => {
     it('should encode ArrayUnion sentinel as-is (for converter to handle)', () => {
       const result = Schema.encodeSync(TestModel.update)({
         name: 'Post',
-        tags: ArrayUnion.values(['c']),
+        tags: arrayUnion(['c']),
       });
       expect(result.tags).toBeInstanceOf(ArrayUnion);
       expect(result.tags.values).toEqual(['c']);
@@ -66,7 +71,7 @@ describe('WithArrayFields', () => {
     it('should encode ArrayRemove sentinel as-is (for converter to handle)', () => {
       const result = Schema.encodeSync(TestModel.update)({
         name: 'Post',
-        tags: ArrayRemove.values(['a']),
+        tags: arrayRemove(['a']),
       });
       expect(result.tags).toBeInstanceOf(ArrayRemove);
       expect(result.tags.values).toEqual(['a']);
@@ -86,7 +91,7 @@ describe('WithArrayFields', () => {
       expect(() =>
         Schema.decodeUnknownSync(TestModel.json)({
           name: 'Post',
-          tags: ArrayUnion.make({ values: ['c'] }),
+          tags: arrayUnion(['c']),
         })
       ).toThrow();
     });
@@ -110,15 +115,15 @@ describe('Array', () => {
   it('update variant accepts ArrayUnion', () => {
     const result = Schema.decodeUnknownSync(TestModel.update)({
       name: 'Post',
-      tags: ArrayUnion.values(['y']),
+      tags: arrayUnion(['y']),
     });
     expect(result.tags).toBeInstanceOf(ArrayUnion);
   });
 
   it('update variant accepts ArrayRemove', () => {
     const result = Schema.decodeUnknownSync(TestModel.update)({
       name: 'Post',
-      tags: ArrayRemove.values(['x']),
+      tags: arrayRemove(['x']),
     });
     expect(result.tags).toBeInstanceOf(ArrayRemove);
   });
diff --git a/packages/effect-firebase/src/lib/firestore/model/array.ts b/packages/effect-firebase/src/lib/firestore/model/array.ts
@@ -1,12 +1,7 @@
 import { Schema } from 'effect';
 import { VariantSchema } from '@effect/experimental';
 import { fieldEvolve } from './core.js';
-import {
-  ArrayUnion,
-  ArrayUnionInstance,
-  ArrayRemove,
-  ArrayRemoveInstance,
-} from '../schema/fields.js';
+import { ArrayUnionInstance, ArrayRemoveInstance } from '../fields/array.js';
 
 /**
  * Adds `ArrayUnion` and `ArrayRemove` sentinel support to an array field's `update` variant.
@@ -25,19 +20,15 @@ import {
  *
  * // update variant accepts:
  * postRepo.update('id', { tags: ['a', 'b'] });              // replace
- * postRepo.update('id', { tags: ArrayUnion.withValues(['c']) });    // arrayUnion
- * postRepo.update('id', { tags: ArrayRemove.withValues(['a']) }); // arrayRemove
+ * postRepo.update('id', { tags: arrayUnion(['c']) });    // arrayUnion
+ * postRepo.update('id', { tags: arrayRemove(['a']) }); // arrayRemove
  * ```
  */
 export type WithArrayFields<S extends Schema.Schema.Any> = VariantSchema.Field<{
   readonly get: S;
   readonly add: S;
   readonly update: Schema.Union<
-    [
-      S,
-      Schema.instanceOf<typeof ArrayUnion>,
-      Schema.instanceOf<typeof ArrayRemove>
-    ]
+    [S, typeof ArrayUnionInstance, typeof ArrayRemoveInstance]
   >;
   readonly json: S;
   readonly jsonAdd: S;
@@ -57,11 +48,7 @@ export const WithArrayFields: <
       readonly [K in keyof S]: S[K] extends Schema.Schema.Any
         ? K extends 'update'
           ? Schema.Union<
-              [
-                S[K],
-                Schema.instanceOf<typeof ArrayUnion>,
-                Schema.instanceOf<typeof ArrayRemove>
-              ]
+              [S[K], typeof ArrayUnionInstance, typeof ArrayRemoveInstance]
             >
           : S[K]
         : never;
diff --git a/packages/effect-firebase/src/lib/firestore/model/optional.spec.ts b/packages/effect-firebase/src/lib/firestore/model/optional.spec.ts
@@ -3,7 +3,7 @@ import { describe, expect, it } from 'vitest';
 import { Class } from './core.js';
 
 import { Optional, OptionalNull, OptionalDeletable } from './optional.js';
-import { Delete } from '../schema/fields.js';
+import { Delete, delete as deleteField } from '../fields/delete.js';
 
 describe('Optional', () => {
   class TestModel extends Class<TestModel>('TestModel')({
@@ -170,7 +170,7 @@ describe('OptionalDeletable', () => {
   describe('update variant', () => {
     it('should decode Delete value to Option.some', () => {
       const decode = Schema.decodeUnknownSync(TestModel.update);
-      const result = decode({ name: 'John', bio: Delete.make() });
+      const result = decode({ name: 'John', bio: deleteField() });
 
       expect(Option.isSome(result.bio)).toBe(true);
       expect(Option.getOrNull(result.bio)).toBeInstanceOf(Delete);
@@ -209,7 +209,7 @@ describe('OptionalDeletable', () => {
       const encode = Schema.encodeSync(TestModel.update);
       const result = encode({
         name: 'John',
-        bio: Option.some(new Delete({})),
+        bio: Option.some(deleteField()),
       });
 
       expect(result.bio).toBeDefined();
diff --git a/packages/effect-firebase/src/lib/firestore/model/optional.ts b/packages/effect-firebase/src/lib/firestore/model/optional.ts
@@ -1,7 +1,7 @@
 import { Schema } from 'effect';
 import { VariantSchema } from '@effect/experimental';
 import { VariantsDatabase, fieldEvolve } from './core.js';
-import { Delete } from '../schema/fields.js';
+import { DeleteInstance } from '../fields/delete.js';
 
 /**
  * Convert a field to one that is optional for all variants.
@@ -102,7 +102,7 @@ export type OptionalDeletable<S extends Schema.Schema.Any> =
     readonly get: Schema.OptionFromUndefinedOr<S>;
     readonly add: Schema.OptionFromUndefinedOr<S>;
     readonly update: Schema.OptionFromUndefinedOr<
-      Schema.Union<[S, typeof Delete]>
+      Schema.Union<[S, typeof DeleteInstance]>
     >;
     readonly json: Schema.optionalWith<S, { as: 'Option' }>;
     readonly jsonAdd: Schema.optionalWith<S, { as: 'Option'; nullable: true }>;
@@ -123,14 +123,16 @@ export const OptionalDeletable: <
       readonly [K in keyof S]: S[K] extends Schema.Schema.Any
         ? K extends VariantsDatabase
           ? Schema.OptionFromUndefinedOr<S[K]>
-          : Schema.OptionFromUndefinedOr<Schema.Union<[S[K], typeof Delete]>>
+          : Schema.OptionFromUndefinedOr<
+              Schema.Union<[S[K], typeof DeleteInstance]>
+            >
         : never;
     }>
   : never = fieldEvolve({
   get: Schema.OptionFromUndefinedOr,
   add: Schema.OptionFromUndefinedOr,
   update: (s: Schema.Schema.Any) =>
-    Schema.OptionFromUndefinedOr(Schema.Union(s, Delete)),
+    Schema.OptionFromUndefinedOr(Schema.Union(s, DeleteInstance)),
   json: Schema.optionalWith({ as: 'Option' }),
   jsonAdd: Schema.optionalWith({ as: 'Option', nullable: true }),
   jsonUpdate: Schema.optionalWith({ as: 'Option', nullable: true }),
diff --git a/packages/effect-firebase/src/lib/firestore/schema/fields.ts b/packages/effect-firebase/src/lib/firestore/schema/fields.ts
diff --git a/packages/effect-firebase/src/lib/firestore/schema/schema.ts b/packages/effect-firebase/src/lib/firestore/schema/schema.ts
@@ -1,4 +1,3 @@
 export * from './timestamp.js';
 export * from './geopoint.js';
 export * from './reference.js';
-export * from './fields.js';

Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,7 @@ import {`
`7`	`7`	`GeoPoint,`
`8`	`8`	`Timestamp,`
`9`	`9`	`} from 'firebase-admin/firestore';`
`10`		`-import { FirestoreSchema } from 'effect-firebase';`
	`10`	`+import { FirestoreSchema, FirestoreField } from 'effect-firebase';`
`11`	`11`
`12`	`12`	`export const toFirestoreDocumentData = (`
`13`	`13`	`db: Firestore,`
`@@ -35,13 +35,13 @@ export const toFirestoreDocumentData = (`
`35`	`35`	`if (data instanceof FirestoreSchema.ServerTimestamp) {`
`36`	`36`	`return FieldValue.serverTimestamp();`
`37`	`37`	`}`
`38`		`- if (data instanceof FirestoreSchema.Delete) {`
	`38`	`+ if (data instanceof FirestoreField.Delete) {`
`39`	`39`	`return FieldValue.delete();`
`40`	`40`	`}`
`41`		`- if (data instanceof FirestoreSchema.ArrayUnion) {`
	`41`	`+ if (data instanceof FirestoreField.ArrayUnion) {`
`42`	`42`	`return FieldValue.arrayUnion(...data.values);`
`43`	`43`	`}`
`44`		`- if (data instanceof FirestoreSchema.ArrayRemove) {`
	`44`	`+ if (data instanceof FirestoreField.ArrayRemove) {`
`45`	`45`	`return FieldValue.arrayRemove(...data.values);`
`46`	`46`	`}`
`47`	`47`	`if (Array.isArray(data)) {`
Original file line number	Diff line number	Diff line change
`@@ -12,7 +12,7 @@ import {`
`12`	`12`	`serverTimestamp,`
`13`	`13`	`Timestamp,`
`14`	`14`	`} from 'firebase/firestore';`
`15`		`-import { FirestoreSchema } from 'effect-firebase';`
	`15`	`+import { FirestoreSchema, FirestoreField } from 'effect-firebase';`
`16`	`16`
`17`	`17`	`export const toFirestoreDocumentData = (`
`18`	`18`	`db: Firestore,`
`@@ -40,13 +40,13 @@ export const toFirestoreDocumentData = (`
`40`	`40`	`if (data instanceof FirestoreSchema.ServerTimestamp) {`
`41`	`41`	`return serverTimestamp();`
`42`	`42`	`}`
`43`		`- if (data instanceof FirestoreSchema.Delete) {`
	`43`	`+ if (data instanceof FirestoreField.Delete) {`
`44`	`44`	`return deleteField();`
`45`	`45`	`}`
`46`		`- if (data instanceof FirestoreSchema.ArrayUnion) {`
	`46`	`+ if (data instanceof FirestoreField.ArrayUnion) {`
`47`	`47`	`return arrayUnion(...data.values);`
`48`	`48`	`}`
`49`		`- if (data instanceof FirestoreSchema.ArrayRemove) {`
	`49`	`+ if (data instanceof FirestoreField.ArrayRemove) {`
`50`	`50`	`return arrayRemove(...data.values);`
`51`	`51`	`}`
`52`	`52`	`if (Array.isArray(data)) {`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`export * as FirestoreSchema from './lib/firestore/schema/schema.js';`
	`2`	`+export * as FirestoreField from './lib/firestore/fields/fields.js';`
`2`	`3`	`export * from './lib/firestore/firestore-service.js';`
`3`	`4`	`export * from './lib/firestore/errors.js';`
`4`	`5`	`export * from './lib/firestore/snapshot.js';`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+export * from './delete.js';`
	`2`	`+export * from './array.js';`