[union] Allow non-empty type arrays

Author: jamesgpearce

site/guides/05_schemas/1_using_schemas.md

@@ -57,8 +57,8 @@ rejected by the schema.
 
 ## Allowing A Union Of Types
 
-Use an array of two or more type names when a Cell or Value can have more than
-one broad type:
+Use a non-empty array of type names to list the broad types that a Cell or Value
+can have:
 
 ```js
 const unionStore = createStore().setValuesSchema({
@@ -70,9 +70,10 @@ console.log(unionStore.getValues());
 // -> {reference: 42, response: {accepted: true}}
 ```
 
-A type union can contain `string`, `number`, `boolean`, `object`, and `array`.
+A type array can contain `string`, `number`, `boolean`, `object`, and `array`.
+Multiple type names form a union, and repeated names have no additional effect.
 Do not include `null` in the array: use `allowNull: true` instead. A default is
-used only when it matches one of the union's types, or is `null` when null is
+used only when it matches one of the array's types, or is `null` when null is
 allowed.
 
 ## Restricting Values With Enums

site/guides/20_releases.md

@@ -37,8 +37,8 @@ supported primitive enum and literal constraints in the schemas they produce.
 
 ## Native Schema Type Unions
 
-CellSchema and ValueSchema can now accept an array in the `type` property when
-a Cell or Value can have more than one broad type:
+CellSchema and ValueSchema can now accept a non-empty array in the `type`
+property to list one or more allowed broad types:
 
 ```js
 const unionStore = createStore().setValuesSchema({
@@ -52,11 +52,12 @@ console.log(unionStore.getValues());
 // -> {reference: 'unknown', response: {accepted: true}}
 ```
 
-A type union must contain at least two of `string`, `number`, `boolean`,
-`object`, and `array`. `null` continues to be represented by `allowNull: true`,
-and defaults are used only when they match one of the listed types. Each schema
-entry still uses exactly one of `type` or `enum`: a type union allows every
-value of its listed types, while an enum allows only its listed values.
+A type array can contain `string`, `number`, `boolean`, `object`, and `array`.
+Multiple type names form a union, and repeated names have no additional effect.
+`null` continues to be represented by `allowNull: true`, and defaults are used
+only when they match one of the listed types. Each schema entry still uses
+exactly one of `type` or `enum`: a type array allows every value of its listed
+types, while an enum allows only its listed values.
 
 The schema-aware Store APIs infer the corresponding TypeScript unions. The
 ArkType, Effect Schema, TypeBox, Valibot, and Zod schematizers also preserve

src/@types/schematizers/docs.js

@@ -52,7 +52,7 @@
  * type, default value, nullable flag, and optional required flag. It should
  * recursively unwrap optional/nullable wrappers and return a tuple of
  * [schema, defaultValue, allowNull, required]. The unwrapped schema should have
- * either a supported `type` property, a `type` array containing two or more
+ * either a supported `type` property, a non-empty `type` array containing
  * supported types, or a non-empty `enum` property containing primitive values.
  * @param getProperties - A function that extracts the properties/entries/shape
  * from an object schema. Returns undefined if the schema is not an object.

src/@types/store/docs.js

@@ -42,11 +42,12 @@
  * Table.
  *
  * A CellSchema specifies either the type of the Cell (`string`, `boolean`,
- * `number`, `object`, or `array`), a union of two or more of those types, or a
- * non-empty `enum` of exact primitive values that are allowed. Use an array for
- * a type union, such as `type: ['string', 'number']`. The `type` and `enum`
- * properties are mutually exclusive, and enum members can be strings, finite
- * numbers, or booleans, including a mixture of those types.
+ * `number`, `object`, or `array`), a non-empty array of those types, or a
+ * non-empty `enum` of exact primitive values that are allowed. Multiple type
+ * names form a union, such as `type: ['string', 'number']`, and repeated names
+ * have no additional effect. The `type` and `enum` properties are mutually
+ * exclusive, and enum members can be strings, finite numbers, or booleans,
+ * including a mixture of those types.
  *
  * For `object` and `array` types, TinyBase automatically serializes values to
  * and from JSON when storing and retrieving them. Their contents should
@@ -154,11 +155,12 @@
  * Store.
  *
  * A ValueSchema specifies either the type of the Value (`string`, `boolean`,
- * `number`, `object`, or `array`), a union of two or more of those types, or a
- * non-empty `enum` of exact primitive values that are allowed. Use an array for
- * a type union, such as `type: ['string', 'number']`. The `type` and `enum`
- * properties are mutually exclusive, and enum members can be strings, finite
- * numbers, or booleans, including a mixture of those types.
+ * `number`, `object`, or `array`), a non-empty array of those types, or a
+ * non-empty `enum` of exact primitive values that are allowed. Multiple type
+ * names form a union, such as `type: ['string', 'number']`, and repeated names
+ * have no additional effect. The `type` and `enum` properties are mutually
+ * exclusive, and enum members can be strings, finite numbers, or booleans,
+ * including a mixture of those types.
  *
  * For `object` and `array` types, TinyBase automatically serializes values to
  * and from JSON when storing and retrieving them. Their contents should

src/@types/store/index.d.ts

@@ -12,7 +12,7 @@ import type {
 
 type SchemaType = 'string' | 'number' | 'boolean' | 'object' | 'array';
 
-type SchemaTypeUnion = readonly [SchemaType, SchemaType, ...SchemaType[]];
+type SchemaTypeArray = readonly [SchemaType, ...SchemaType[]];
 
 /// TablesSchema
 export type TablesSchema = {[tableId: Id]: {[cellId: Id]: CellSchema}};
@@ -55,7 +55,7 @@ export type CellSchema =
       enum?: never;
     }
   | {
-      type: SchemaTypeUnion;
+      type: SchemaTypeArray;
       default?: string | number | boolean | AnyObject | AnyArray | null;
       allowNull?: boolean;
       required?: boolean;
@@ -113,7 +113,7 @@ export type ValueSchema =
       enum?: never;
     }
   | {
-      type: SchemaTypeUnion;
+      type: SchemaTypeArray;
       default?: string | number | boolean | AnyObject | AnyArray | null;
       allowNull?: boolean;
       required?: boolean;

src/@types/store/with-schemas/index.d.ts

@@ -25,7 +25,7 @@ import type {
 
 type SchemaType = 'string' | 'number' | 'boolean' | 'object' | 'array';
 
-type SchemaTypeUnion = readonly [SchemaType, SchemaType, ...SchemaType[]];
+type SchemaTypeArray = readonly [SchemaType, ...SchemaType[]];
 
 type CellOrValueFromSchemaType<Type> = Type extends readonly (infer Type)[]
   ? CellOrValueFromSchemaType<Type>
@@ -82,7 +82,7 @@ export type CellSchema =
       enum?: never;
     }
   | {
-      type: SchemaTypeUnion;
+      type: SchemaTypeArray;
       default?: string | number | boolean | AnyObject | AnyArray | null;
       allowNull?: boolean;
       required?: boolean;
@@ -140,7 +140,7 @@ export type ValueSchema =
       enum?: never;
     }
   | {
-      type: SchemaTypeUnion;
+      type: SchemaTypeArray;
       default?: string | number | boolean | AnyObject | AnyArray | null;
       allowNull?: boolean;
       required?: boolean;

src/common/cell.ts

@@ -40,11 +40,7 @@ export type CellOrValueSchemaType = Exclude<CellOrValueType, 'null'>;
 
 export type CellOrValueSchemaTypes =
   | CellOrValueSchemaType
-  | readonly [
-      CellOrValueSchemaType,
-      CellOrValueSchemaType,
-      ...CellOrValueSchemaType[],
-    ];
+  | readonly [CellOrValueSchemaType, ...CellOrValueSchemaType[]];
 
 export const getCellOrValueType = (
   cellOrValue: any,
@@ -80,7 +76,7 @@ export const isCellOrValueSchemaTypes = (
   types: any,
 ): types is CellOrValueSchemaTypes =>
   isArray(types)
-    ? !isUndefined(types[1]) && arrayEvery(types, isCellOrValueSchemaType)
+    ? !isUndefined(types[0]) && arrayEvery(types, isCellOrValueSchemaType)
     : isCellOrValueSchemaType(types);
 
 export const cellOrValueSchemaTypeIncludes = (

test/unit/core/store/store-schema.test.ts

@@ -278,6 +278,8 @@ describe.each([
           answer: {type: ['string', 'number'], default: 'unknown'},
           payload: {type: ['object', 'array'], required: true},
           score: {type: ['number', 'boolean'], allowNull: true},
+          single: {type: ['string']},
+          repeated: {type: ['string', 'string']},
           status: {enum: ['draft', 'live']},
         },
       } as const;
@@ -287,33 +289,45 @@ describe.each([
       store.setRow('pets', 'pet1', {
         payload: {likes: ['walks']},
         score: null,
+        single: 'initial',
+        repeated: 'initial',
         status: 'draft',
       });
       expect(store.getRow('pets', 'pet1')).toEqual({
         answer: 'unknown',
         payload: {likes: ['walks']},
         score: null,
+        single: 'initial',
+        repeated: 'initial',
         status: 'draft',
       });
 
       store.setCell('pets', 'pet1', 'answer', 42);
       store.setCell('pets', 'pet1', 'payload', ['walks']);
       store.setCell('pets', 'pet1', 'score', true);
+      store.setCell('pets', 'pet1', 'single', 'one');
+      store.setCell('pets', 'pet1', 'repeated', 'two');
       expect(store.getRow('pets', 'pet1')).toEqual({
         answer: 42,
         payload: ['walks'],
         score: true,
+        single: 'one',
+        repeated: 'two',
         status: 'draft',
       });
 
       store.setCell('pets', 'pet1', 'answer', false);
       store.setCell('pets', 'pet1', 'payload', null);
       store.setCell('pets', 'pet1', 'score', 'high');
+      store.setCell('pets', 'pet1', 'single', 1);
+      store.setCell('pets', 'pet1', 'repeated', false);
       store.setCell('pets', 'pet1', 'status', 'other');
       expect(store.getRow('pets', 'pet1')).toEqual({
         answer: 'unknown',
         payload: ['walks'],
         score: true,
+        single: 'one',
+        repeated: 'two',
         status: 'draft',
       });
       expectChanges(
@@ -322,6 +336,8 @@ describe.each([
         {pets: {pet1: {answer: [false]}}},
         {pets: {pet1: {payload: [null]}}},
         {pets: {pet1: {score: ['high']}}},
+        {pets: {pet1: {single: [1]}}},
+        {pets: {pet1: {repeated: [false]}}},
         {pets: {pet1: {status: ['other']}}},
       );
 
@@ -342,7 +358,6 @@ describe.each([
 
       for (const answer of [
         {type: []},
-        {type: ['string']},
         {type: ['string', 'null']},
         {type: ['string', 'date']},
         {type: ['string', 'boolean'], enum: ['draft']},
@@ -579,6 +594,8 @@ describe.each([
         answer: {type: ['string', 'number'], default: 'unknown'},
         payload: {type: ['object', 'array'], required: true},
         score: {type: ['number', 'boolean'], allowNull: true},
+        single: {type: ['string']},
+        repeated: {type: ['string', 'string']},
         status: {enum: ['draft', 'live']},
       } as const;
       store.setValuesSchema(valuesSchema);
@@ -587,40 +604,54 @@ describe.each([
         'invalids',
         {payload: [undefined]},
         {score: [undefined]},
+        {single: [undefined]},
+        {repeated: [undefined]},
         {status: [undefined]},
       );
       expect(JSON.parse(store.getValuesSchemaJson())).toEqual(valuesSchema);
 
       store.setValues({
         payload: {likes: ['walks']},
         score: null,
+        single: 'initial',
+        repeated: 'initial',
         status: 'draft',
       });
       expect(store.getValues()).toEqual({
         answer: 'unknown',
         payload: {likes: ['walks']},
         score: null,
+        single: 'initial',
+        repeated: 'initial',
         status: 'draft',
       });
 
       store.setValue('answer', 42);
       store.setValue('payload', ['walks']);
       store.setValue('score', true);
+      store.setValue('single', 'one');
+      store.setValue('repeated', 'two');
       expect(store.getValues()).toEqual({
         answer: 42,
         payload: ['walks'],
         score: true,
+        single: 'one',
+        repeated: 'two',
         status: 'draft',
       });
 
       store.setValue('answer', false);
       store.setValue('payload', null);
       store.setValue('score', 'high');
+      store.setValue('single', 1);
+      store.setValue('repeated', false);
       store.setValue('status', 'other');
       expect(store.getValues()).toEqual({
         answer: 'unknown',
         payload: ['walks'],
         score: true,
+        single: 'one',
+        repeated: 'two',
         status: 'draft',
       });
       expectChanges(
@@ -629,6 +660,8 @@ describe.each([
         {answer: [false]},
         {payload: [null]},
         {score: ['high']},
+        {single: [1]},
+        {repeated: [false]},
         {status: ['other']},
       );
 
@@ -647,7 +680,6 @@ describe.each([
 
       for (const answer of [
         {type: []},
-        {type: ['string']},
         {type: ['string', 'null']},
         {type: ['string', 'date']},
         {type: ['string', 'boolean'], enum: ['draft']},