@tryghost/metafield-types 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # @tryghost/metafield-types
 
+## 0.4.0
+
+### Minor Changes
+
+- Changed how a write clears a value, and described each field shape's rules once, in the package.
+
+  - `null` is the only way a write clears. A write of `''` to a text field, `[]` to a list, or `''` to a part of an address is refused by `valueSchemaFor` with a message saying to send `null`. A part of an address named as `null` is cleared; before, `null` for a part was refused.
+  - A value never holds nothing: a field holding nothing has no value, rather than an empty one. `ValueOf<T>` and `FieldValue` no longer admit `null` or `''` parts, and a write has its own type, `WriteOf<T>` and `FieldWrite`, which does.
+  - `./shapes` is a new entry point, zod-free like `./structure`. `SHAPES` holds each shape's rules (`parse`, `same`, `apply`, `diff`), `LEAVES` each kind of leaf's (its JSON kind, `read`, `fromText`), and `FIELD_READING` how a field reads a held value (`held`, `editable`). `shaped(field)` and `shapedType(type)` pair a field or type with its shape, so a table keyed by shape can be indexed with it without a cast. `heldValue`, `editableValue`, `valueFromText`, `textOfValue`, `heldTextOf`, `formTextOf`, `formShows` and `formWrite` read a held value and work out the write a form makes.
+  - `accept(shaped(field), raw)` checks a write against the field's strict rule and returns an `Accepted` value branded with its shape, so code that stores a value can require one that passed the rule.
+  - `keysOf(value)` lists an object's keys typed as its type's keys. `LeafValues`, `LeafValue`, `LeafKind` and `WriteOf` are exported from `./structure`.
+
+- Changed a repeated list option to be refused on the option that repeats an earlier one, and options to repeat each other whatever their case.
+
+  - `SetSettingsSchema` refuses a repeat at `options.<index>` of the later option, with "This option already exists.". It used to refuse the list at `options` with "Give each option once.".
+  - Two options are the same option when their text matches without regard to case, so a list can't offer both "Podcasts" and "podcasts". It used to compare text exactly.
+  - `optionKey(option)` is exported from `./structure`: the text two options are compared by, so a client that tidies a list skips the same repeats the schema refuses.
+
+## 0.3.0
+
+### Minor Changes
+
+- Changed the catalog to describe each field type as a composition of building blocks, and to derive each type's rule from them.
+
+  - `FIELD_STRUCTURES` replaces `FIELD_PARTS`. A type is one leaf, `{ shape: 'scalar', leaf }`, or a record of named leaves, `{ shape: 'record', parts }`.
+  - A leaf is text of a size, `text(size)` with `TEXT_SIZES`, or a choice from a list, `choice(from)` with `LIST_SOURCES`. `country` is the choice from the list of countries.
+  - A part's type is now its leaf, so `PART_TYPE_IDS`, `PartType` and `partTypesOf` are removed. An address's postal code is `text('code')`, its country is `country`, and its other parts are `text('line')`.
+  - `FIELD_KINDS` and `FieldKind` are removed. A scalar's leaf says what it holds.
+  - `matchShape(type, { scalar, record })` and `matchLeaf(leaf, { text, choice })` call the handler for a type's shape or a leaf's kind, so a caller has to say what it does with every one. `matchShape` throws for a type the package doesn't know, so check a type from the wire with `isFieldType` first.
+  - `isRecordValue` tells whether a value is laid out as a record of parts.
+  - `StructureOf`, `ShapeOf`, `FieldTypeOfShape` and `PartsOf` name what a type is composed of, and `ValueOf` names the value it holds.
+  - `partsOf` names a record's parts as plain strings. Read one type's parts by name from `FIELD_STRUCTURES[type].parts`, whose keys are typed.
+  - `valueSchemaFor(field)` is the rule a value of one field must satisfy, derived from its type's composition. It replaces `FIELD_TYPES`, `FieldTypeDefinition`, `PART_TYPES` and `AddressValue`, which are removed. `FieldValue` and `Address` stay.
+
+- Added helpers for editing a list field's answers.
+
+  - `inOptionOrder(settings, held)` is the answers among `held` that a list offers, in its order, and `editableAnswers(settings, held)` is what a form editing a list's answers starts from: none while a field taking one holds several.
+
+- Added the list field type, whose field offers options of its own and takes one or several of them.
+
+  - `list` is `{ shape: 'set' }`: a value is the text of each option picked, as `string[]`, even when the field takes one. `matchShape` handlers take a `set` branch.
+  - A field now carries `settings` beside its `type`. `SettingsOf<T>` is what a type is set up with: `SetSettings` (`options`, in the order shown, and `multiple`) for a list, and nothing for every other type, so a field of another type has no settings. `TypedSettings` pairs a type with its settings. `withTypedSettings(base, settings)` builds what a field holds beside its type with that pair, a variant per shape, from how each shape's settings are held: `WRITTEN_SETTINGS` checks them against the rules, and `READ_SETTINGS` reads them back by `SetSettingsShape` alone, so a rule tightened later never hides a field set up under the old one. `TypedSettingsInputSchema` and `TypedSettingsSchema` are the pair on its own, and `MetafieldDefinitionSchema` is built the same way. `typesOfShape(shape)` lists the types of a shape.
+  - `MetafieldDefinitionSchema` reads `settings`, and `MetafieldDefinition` is typed by them, so a list definition always has its options.
+  - `valueSchemaFor(field)` takes the field's type and settings. A list's rule accepts only the options its field offers, and at most one when it takes one.
+  - `matchField(field, handlers)` calls a handler for the field's shape with the field narrowed, settings included.
+  - `optionText` is how an option's text is matched: trimmed, with accents encoded one way. `MIN_OPTIONS`, `MAX_OPTIONS` and `OPTION_SEPARATOR` are a list's limits and the character joining options in one CSV cell, which no option may contain.
+
+- Added `SHAPE_SETTINGS`, each field shape's settings in one place: the shape a read is checked against, the rules a write is checked against on top of that shape, and the defaults a field starts with. `WRITTEN_SETTINGS` and `READ_SETTINGS` are now taken from it, and `SetSettingsSchema` is now built on `SetSettingsShape`.
+
+- Added `refusedProperty(path)`, which names where a refusal points within what was sent by its path, with parts and positions joined by dots, such as `settings.options.2` for a field's third option. Ghost reports a custom field refusal's `property` this way, and a form can file the problems it finds under the same keys.
+
+- Added the shape of a field definition as the Admin and Members APIs return it.
+
+  - `MetafieldDefinitionSchema` reads a definition (namespace, key, name, type, status, member access and dates) and `MetafieldDefinition` is the type it produces. Ghost writes every definition through it.
+  - `FIELD_STATUSES`, `FieldStatusSchema`, `FIELD_STATUS` and `FieldStatus` name whether a field is active or archived.
+
+### Patch Changes
+
+- Pointed the README at a guide for Ghost contributors adding a field type.
+
+- Updated dependencies
+
+- Updated dependencies
+
+- Updated dependencies
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -1,9 +1,9 @@
 # @tryghost/metafield-types
 
-The types of member custom field Ghost supports: which types exist, which parts a
-type is made of, the type of value each part holds, and how a value of each type is
-validated. Ghost, its Admin and Portal use it, and so can an integration that offers
-inputs for a site's custom fields, such as the Ghost Zapier integration.
+The types of member custom field Ghost supports: which types exist, what each type
+is composed of, and how a value of each type is validated. Ghost, its Admin and Portal
+use it, and so can an integration that offers inputs for a site's custom fields, such
+as the Ghost Zapier integration.
 
 ```bash
 npm install @tryghost/metafield-types
@@ -11,31 +11,37 @@ npm install @tryghost/metafield-types
 
 ## Entry points
 
-- `@tryghost/metafield-types/structure`: the type ids, each type's parts and the
-  type of value each part holds. It depends on nothing.
-- `@tryghost/metafield-types/countries`: the two-letter country codes a country
-  part accepts. It depends on nothing.
+- `@tryghost/metafield-types/structure`: the type ids and what each type is composed
+  of. A type is one leaf, a record of named leaves, or a set of options its field
+  offers, and a leaf is text of a size or a choice from a list, such as a country. A
+  field of a set type is set up with its options, which a field carries as its
+  `settings`. It depends on nothing.
+- `@tryghost/metafield-types/countries`: the two-letter country codes the list of
+  countries offers. It depends on nothing.
 - `@tryghost/metafield-types/identity`: how a field is named everywhere: its
   namespace, its key, the parts of a record value, and the identity they make
   together (`custom.shipping_address.country`). Each is a type that only its
   check produces. It loads `zod/mini`, a small fraction of zod's size, so a
   browser app can check identities without paying for the rest.
-- `@tryghost/metafield-types`: the structure above, plus the rules that validate
-  a value of each type. These are built on [zod](https://zod.dev), and only this
-  entry point loads all of it, so an integration that only draws inputs can use
-  `./structure` and `./countries` without loading zod at all.
+- `@tryghost/metafield-types`: the structure above, plus `valueSchemaFor(field)`,
+  the rule a value of a field must satisfy given its type and settings. The rules are built on
+  [zod](https://zod.dev), and only this entry point loads all of it, so an
+  integration that only draws inputs can use `./structure` and `./countries`
+  without loading zod at all.
 
 ## Compatibility
 
 An integration using this package talks to sites on many Ghost versions, so a type
-never changes once it has shipped: it keeps its parts and the type of value each
-holds. New structure arrives as a new type. An integration should skip a type it
-doesn't recognise, which is what happens when a site is on a newer Ghost than the
-package the integration was built with.
+never changes once it has shipped. It keeps what it is composed of: its shape, its
+leaves, and the names of any parts. New structure arrives as a new type. An integration
+should skip a type it doesn't recognise, which is what happens when a site is on a newer
+Ghost than the package the integration was built with.
 
 ## Develop
 
-This is a workspace package in the Ghost monorepo. From the repo root:
+This is a workspace package in the Ghost monorepo. Adding a field type to Ghost is
+covered in [`docs/adding-a-field-type.md`](docs/adding-a-field-type.md). From the repo
+root:
 
 ```bash
 pnpm --filter @tryghost/metafield-types build   # compile to build/ with tsc (ESM)
@@ -52,9 +58,9 @@ imports in `src/` must carry an explicit extension; write the real `.ts` one —
 `import {x} from './x.ts'` — and `tsc` rewrites it to `.js` on emit
 (`rewriteRelativeImportExtensions`).
 
-`./structure` is the half of the catalog a renderer needs — which parts a field type
-has, and what each holds — and it stands apart from `./index` so that importing it
-costs a bundle almost nothing. The rules in `./index` are built on zod, some
+`./structure` is the half of the catalog a renderer needs, what each field type is
+composed of, and it stands apart from `./index` so that importing it costs a bundle
+almost nothing. The rules in `./index` are built on zod, some
 seventeen kilobytes gzipped that a renderer never runs. Portal imports `./structure`
 and loads on every page view of every themed site, so the difference reaches every
 visitor of every Ghost site.

package/build/index.d.ts

@@ -1,6 +1,8 @@
 import { z } from 'zod';
-import { type FieldType } from './structure.js';
-export { FIELD_KINDS, FIELD_PARTS, FIELD_TYPE_IDS, PART_TYPE_IDS, partTypesOf, partsOf, type FieldKind, type FieldType, type PartsOf, type PartType, } from './structure.js';
+import { type FieldType, type FieldShape, type TypedSettings, type ValueOf, type WriteOf } from './structure.js';
+import { type ShapeWrite, type ShapedField } from './shapes.js';
+export { FIELD_READING, LEAVES, SHAPES, editableValue, formShows, formTextOf, heldTextOf, formWrite, heldValue, leafFromText, shaped, shapedType, textOfValue, valueFromText, type AnyLeafValue, type FieldReading, type ShapeRules, type ShapeText, type ShapeValue, type ShapeWrite, type ShapedField, type ShapedType, type ValueKind, type ValueOfKind, } from './shapes.js';
+export { FIELD_STRUCTURES, FIELD_TYPE_IDS, LIST_SOURCES, MAX_OPTIONS, MIN_OPTIONS, OPTION_SEPARATOR, TEXT_SIZES, choice, country, editableAnswers, inOptionOrder, isFieldType, isRecordValue, matchField, matchLeaf, matchShape, partsOf, text, type ChoiceLeaf, type FieldHandlers, type FieldOfShape, type FieldShape, type FieldStructure, type FieldType, type FieldTypeOfShape, type Leaf, type LeafHandlers, type LeafKind, type LeafValue, type LeafValues, type ListSource, type PartsOf, type RecordStructure, type ScalarStructure, type SetSettings, type SetStructure, type SettingsOf, type ShapeHandlers, type ShapeOf, type StructureOf, type TextLeaf, type TextSize, type TypedSettings, type ValueOf, type WriteOf, keysOf, } from './structure.js';
 /**
  * The shared catalog of member metafield types.
  *
@@ -10,17 +12,18 @@ export { FIELD_KINDS, FIELD_PARTS, FIELD_TYPE_IDS, PART_TYPE_IDS, partTypesOf, p
  * last statement lives here and nowhere else, so that Ghost core, which enforces it, and
  * admin, which gives instant feedback against it, cannot disagree about what is valid.
  *
- * A type is one of two things. Most are a value in their own right, declared as the
- * schema that value must satisfy. An address is a *record*: a set of named parts, each a
- * value in the same sense, from which the whole type's schema is derived. Nothing stops a
- * part being a record itself.
+ * A type is composed of leaves, each one value with its own rule. Most types are a single
+ * leaf. An address is a *record*: a set of named parts, each a leaf, from which the whole
+ * type's rule is derived. A part is always a leaf, never a record itself.
  *
  * ## What a write may say
  *
- * A value is text, and so is every part of one. A write names what it means to change: a
- * name it does not mention is left as it was, and a name given an empty string is being
- * cleared. That is why every part accepts empty regardless of its own rule — emptying is
- * a statement about the write, not about the part.
+ * A value is a leaf's value, and so is every part of one. A write names what it means to
+ * change: a name it does not mention is left as it was, and a name given `null` is being
+ * cleared, whatever kind of leaf it holds. That is why every part accepts `null` regardless of
+ * its own rule: clearing is a statement about the write, not about the part. A value is never
+ * empty, so text of nothing but spaces, or a list picking nothing, is refused rather than being
+ * a second way of holding nothing.
  *
  * A name nobody recognizes is an error rather than a silent drop, at both depths. A
  * misspelled field key is refused by the values service, which alone knows which fields a
@@ -51,12 +54,13 @@ export { FIELD_KINDS, FIELD_PARTS, FIELD_TYPE_IDS, PART_TYPE_IDS, partTypesOf, p
  * answer and a disagreement between them is a file that silently stops round-tripping.
  *
  * The line is whether more than one renderer must agree on a string, not presentation
- * against validity — the sentences above are presentation. Admin is the only renderer
- * today, so a part's label lives there, held against this file by a type. A Portal
- * collection form, which cannot reach admin's packages, moves the labels here.
+ * against validity — the sentences above are presentation. Admin and Portal each label a
+ * record's parts in their own words, and each is held against the catalog by a type, so a
+ * part added there fails to compile in both until it has a label.
  */
 export declare const FieldTypeSchema: z.ZodEnum<{
     address: "address";
+    list: "list";
     long_text: "long_text";
     short_text: "short_text";
 }>;
@@ -81,6 +85,268 @@ export declare const MEMBER_ACCESS: {
     readonly read: 'read';
     readonly write: 'write';
 };
+/**
+ * Whether a field is in use. An archived field keeps its definition and the values members
+ * hold for it, so it can be restored, but it takes no new values and members no longer see it.
+ */
+export declare const FIELD_STATUSES: readonly ['active', 'archived'];
+export type FieldStatus = (typeof FIELD_STATUSES)[number];
+export declare const FieldStatusSchema: z.ZodEnum<{
+    active: "active";
+    archived: "archived";
+}>;
+export declare const FIELD_STATUS: {
+    readonly active: 'active';
+    readonly archived: 'archived';
+};
+/**
+ * A set field's settings as stored or sent back: their shape alone, which every read checks. A
+ * write checks the rules `SetSettingsSchema` layers on top, so a rule tightened later never hides
+ * a field set up under the old one, the way a value's rule never hides what a member already holds.
+ */
+export declare const SetSettingsShape: z.ZodObject<{
+    options: z.ZodArray<z.ZodString>;
+    multiple: z.ZodBoolean;
+}, z.core.$strip>;
+/**
+ * What a set field is set up with: its shape, with each option's text tidied and the rules a write
+ * must meet on top. Options are a set as well, so the same option, compared by `optionKey`, can't
+ * be offered twice: the option that repeats an earlier one is refused, so a form shows the problem
+ * beside the option to change. They are listed in the order they are shown.
+ */
+export declare const SetSettingsSchema: z.ZodPipe<z.ZodObject<{
+    options: z.ZodArray<z.ZodString>;
+    multiple: z.ZodBoolean;
+}, z.core.$strip>, z.ZodTransform<{
+    options: string[];
+    multiple: boolean;
+}, {
+    options: string[];
+    multiple: boolean;
+}>>;
+/**
+ * What a field holds beside its type, `base`, with its type and the settings that type's shape
+ * takes, held as `settings` says for each shape: a set's options, and nothing for any other shape.
+ * One variant per shape, so a field's settings are always read against its type. Writes give the
+ * rules, reads the shape alone, and Ghost's table its column.
+ */
+export declare const withTypedSettings: <Base extends z.ZodRawShape, ForScalar extends z.ZodType, ForRecord extends z.ZodType, ForSet extends z.ZodType>(base: Base, settings: {
+    scalar: ForScalar;
+    record: ForRecord;
+    set: ForSet;
+} & { [S in FieldShape]: z.ZodType; }) => z.ZodDiscriminatedUnion<[z.ZodObject<Base & {
+    type: z.ZodEnum<{
+        long_text: "long_text";
+        short_text: "short_text";
+    }>;
+    settings: ForScalar & z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+} extends infer T ? { -readonly [P in keyof T]: T[P]; } : never, z.core.$strip>, z.ZodObject<Base & {
+    type: z.ZodEnum<{
+        address: "address";
+    }>;
+    settings: ForRecord & z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+} extends infer T_1 ? { -readonly [P in keyof T_1]: T_1[P]; } : never, z.core.$strip>, z.ZodObject<Base & {
+    type: z.ZodEnum<{
+        list: "list";
+    }>;
+    settings: ForSet & z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+} extends infer T_2 ? { -readonly [P in keyof T_2]: T_2[P]; } : never, z.core.$strip>], "type">;
+/**
+ * Each shape's settings in one place: a set's options and whether a member picks several, and
+ * nothing for any other shape. A list's defaults have no options, which a list's write rules
+ * refuse, so an edit of a list read with its defaults always writes the settings it is given.
+ * Keyed by shape, so a shape added to the catalog fails to compile until it has an entry.
+ */
+export declare const SHAPE_SETTINGS: {
+    scalar: {
+        written: z.ZodOptional<z.ZodUndefined>;
+        read: z.ZodOptional<z.ZodUndefined>;
+        defaults: undefined;
+    };
+    record: {
+        written: z.ZodOptional<z.ZodUndefined>;
+        read: z.ZodOptional<z.ZodUndefined>;
+        defaults: undefined;
+    };
+    set: {
+        written: z.ZodPipe<z.ZodObject<{
+            options: z.ZodArray<z.ZodString>;
+            multiple: z.ZodBoolean;
+        }, z.core.$strip>, z.ZodTransform<{
+            options: string[];
+            multiple: boolean;
+        }, {
+            options: string[];
+            multiple: boolean;
+        }>>;
+        read: z.ZodObject<{
+            options: z.ZodArray<z.ZodString>;
+            multiple: z.ZodBoolean;
+        }, z.core.$strip>;
+        defaults: {
+            options: never[];
+            multiple: false;
+        };
+    };
+};
+/** Each shape's settings as a write states them, checked against the rules. */
+export declare const WRITTEN_SETTINGS: {
+    scalar: z.ZodOptional<z.ZodUndefined>;
+    record: z.ZodOptional<z.ZodUndefined>;
+    set: z.ZodPipe<z.ZodObject<{
+        options: z.ZodArray<z.ZodString>;
+        multiple: z.ZodBoolean;
+    }, z.core.$strip>, z.ZodTransform<{
+        options: string[];
+        multiple: boolean;
+    }, {
+        options: string[];
+        multiple: boolean;
+    }>>;
+};
+/** Each shape's settings as they are read back, checked for their shape alone. */
+export declare const READ_SETTINGS: {
+    scalar: z.ZodOptional<z.ZodUndefined>;
+    record: z.ZodOptional<z.ZodUndefined>;
+    set: z.ZodObject<{
+        options: z.ZodArray<z.ZodString>;
+        multiple: z.ZodBoolean;
+    }, z.core.$strip>;
+};
+/**
+ * Where a refusal points within what was sent: the path to the refused value, with its parts and
+ * positions joined by dots, such as `settings.options.2` for a field's third option. Ghost names
+ * a refusal's `property` this way, and a form files the problems it finds under the same keys, so
+ * each lands beside the input that set the value.
+ */
+export declare function refusedProperty(path: readonly PropertyKey[]): string;
+/**
+ * A field's type and settings as a write states them, checked together and against the rules:
+ * the settings must be what that type is set up with, so a list carries its options and
+ * nothing else carries any.
+ */
+export declare const TypedSettingsInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodEnum<{
+        long_text: "long_text";
+        short_text: "short_text";
+    }>;
+    settings: z.ZodOptional<z.ZodUndefined> & z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodEnum<{
+        address: "address";
+    }>;
+    settings: z.ZodOptional<z.ZodUndefined> & z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodEnum<{
+        list: "list";
+    }>;
+    settings: z.ZodPipe<z.ZodObject<{
+        options: z.ZodArray<z.ZodString>;
+        multiple: z.ZodBoolean;
+    }, z.core.$strip>, z.ZodTransform<{
+        options: string[];
+        multiple: boolean;
+    }, {
+        options: string[];
+        multiple: boolean;
+    }>> & z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+}, z.core.$strip>], "type">;
+/** A field's type and settings as they are read back: paired, but checked for their shape alone. */
+export declare const TypedSettingsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodEnum<{
+        long_text: "long_text";
+        short_text: "short_text";
+    }>;
+    settings: z.ZodOptional<z.ZodUndefined> & z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodEnum<{
+        address: "address";
+    }>;
+    settings: z.ZodOptional<z.ZodUndefined> & z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodEnum<{
+        list: "list";
+    }>;
+    settings: z.ZodObject<{
+        options: z.ZodArray<z.ZodString>;
+        multiple: z.ZodBoolean;
+    }, z.core.$strip> & z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+}, z.core.$strip>], "type">;
+/**
+ * A field definition as the Admin and Members APIs return it. Ghost writes every definition through
+ * this and Admin reads every one through it, so both ends are checked against one shape. Portal
+ * uses the type without the check, because zod would add to every page view on every site. Dates
+ * are ISO strings, as JSON carries them.
+ */
+export declare const MetafieldDefinitionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodEnum<{
+        long_text: "long_text";
+        short_text: "short_text";
+    }>;
+    settings: z.ZodOptional<z.ZodUndefined> & z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    namespace: z.core.$ZodBranded<import("zod/mini").ZodMiniString<string>, "Namespace", "out">;
+    key: z.core.$ZodBranded<import("zod/mini").ZodMiniString<string>, "Key", "out">;
+    name: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        archived: "archived";
+    }>;
+    access: z.ZodObject<{
+        member: z.ZodEnum<{
+            none: "none";
+            read: "read";
+            write: "write";
+        }>;
+    }, z.core.$strip>;
+    created_at: z.ZodISODateTime;
+    updated_at: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodEnum<{
+        address: "address";
+    }>;
+    settings: z.ZodOptional<z.ZodUndefined> & z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    namespace: z.core.$ZodBranded<import("zod/mini").ZodMiniString<string>, "Namespace", "out">;
+    key: z.core.$ZodBranded<import("zod/mini").ZodMiniString<string>, "Key", "out">;
+    name: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        archived: "archived";
+    }>;
+    access: z.ZodObject<{
+        member: z.ZodEnum<{
+            none: "none";
+            read: "read";
+            write: "write";
+        }>;
+    }, z.core.$strip>;
+    created_at: z.ZodISODateTime;
+    updated_at: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodEnum<{
+        list: "list";
+    }>;
+    settings: z.ZodObject<{
+        options: z.ZodArray<z.ZodString>;
+        multiple: z.ZodBoolean;
+    }, z.core.$strip> & z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    namespace: z.core.$ZodBranded<import("zod/mini").ZodMiniString<string>, "Namespace", "out">;
+    key: z.core.$ZodBranded<import("zod/mini").ZodMiniString<string>, "Key", "out">;
+    name: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        archived: "archived";
+    }>;
+    access: z.ZodObject<{
+        member: z.ZodEnum<{
+            none: "none";
+            read: "read";
+            write: "write";
+        }>;
+    }, z.core.$strip>;
+    created_at: z.ZodISODateTime;
+    updated_at: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strip>], "type">;
+export type MetafieldDefinition = z.output<typeof MetafieldDefinitionSchema>;
 /**
  * Where a change to a member's values was made, as a member's activity feed names it.
  * Shared so a place added on the server is one Admin has to be told how to describe.
@@ -117,59 +383,43 @@ export interface MetafieldChangeEntry<TDate = string> {
  */
 export declare const MAX_LONG_TEXT_BYTES = 65535;
 /**
- * The types a composite's parts can declare, each defined once with its rule. A country
- * code and a postal code both store short text, but they are different things — the
- * part's type is what a control or a filter dispatches on, the way a field's own type
- * is for a scalar.
+ * A value of any field type, as a caller holding a field of unknown type must accept it.
  */
-export declare const PART_TYPES: {
-    short_text: z.ZodString;
-    postal_code: z.ZodString;
-    country_code: z.ZodString;
-};
-export interface FieldTypeDefinition {
-    /** What kind of value this is, for anything that has to compare one. */
-    kind: import('./structure.js').FieldKind;
-    value: z.ZodType;
-}
-export declare const FIELD_TYPES: {
-    short_text: {
-        kind: "text";
-        value: z.ZodString;
-    };
-    long_text: {
-        kind: "text";
-        value: z.ZodString;
-    };
-    address: {
-        kind: 'record';
-        value: z.ZodObject<{
-            line1: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
-            line2: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
-            city: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
-            state: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
-            postal_code: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
-            country: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
-        }, z.core.$strict>;
+export type FieldValue = ValueOf<FieldType>;
+/** A write to a field of any type, as a caller holding a field of unknown type must give it. */
+export type FieldWrite = WriteOf<FieldType>;
+export type Address = ValueOf<'address'>;
+/**
+ * A value a field's rule accepted for writing, tidied as the rule tidies it. Only `accept` makes
+ * one, so a value that skipped the rule can't be handed to code that stores it.
+ */
+export type Accepted<S extends FieldShape> = ShapeWrite[S] & z.core.$brand<'accepted'>;
+/** An accepted value with its shape, so a table keyed by shape can be indexed with it. */
+export type AcceptedValue<S extends FieldShape = FieldShape> = {
+    [K in S]: {
+        readonly shape: K;
+        readonly value: Accepted<K>;
     };
+}[S];
+export type Acceptance<S extends FieldShape = FieldShape> = {
+    readonly success: true;
+    readonly accepted: AcceptedValue<S>;
+} | {
+    readonly success: false;
+    readonly issues: readonly z.core.$ZodIssue[];
 };
-/** Named for the admin types built on it, which speak of an address rather than a record. */
-export declare const AddressValue: z.ZodObject<{
-    line1: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
-    line2: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
-    city: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
-    state: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
-    postal_code: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
-    country: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
-}, z.core.$strict>;
-export type Address = z.infer<typeof AddressValue>;
 /**
- * A value of any field type, as a caller holding a field of unknown type must accept it.
- *
- * Derived from the schemas rather than listed, so a type added here widens it without
- * anyone remembering to.
+ * Strict, for a write, under the field's rule today: only options the field offers now, one answer
+ * when it takes one, and each part valid under its leaf's rule. What a held value reads as is
+ * lenient instead, and is `FIELD_READING`'s to say.
+ */
+export declare function accept<S extends FieldShape>(of: ShapedField<TypedSettings, S>, raw: unknown): Acceptance<S>;
+/**
+ * The rule a write to one field must satisfy, which parses to the write it accepts: a record's
+ * part named as `null` clears it. It takes the field rather than its type so that a
+ * rule depending on the field's own setup, such as the options a list field offers, changes here
+ * and nowhere else; such a rule is built from the field rather than kept per type. Throws for a
+ * type this build doesn't know.
  */
-export type FieldValue = {
-    [T in FieldType]: z.infer<(typeof FIELD_TYPES)[T]['value']>;
-}[FieldType];
+export declare function valueSchemaFor(field: TypedSettings): z.ZodType<FieldWrite>;
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAA+B,KAAK,SAAS,EAAiB,MAAM,gBAAgB,CAAC;AAI5F,OAAO,EACL,WAAW,EACX,WAAW,EACX,cAAc,EACd,aAAa,EACb,WAAW,EACX,OAAO,EACP,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,OAAO,EACZ,KAAK,QAAQ,GACd,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,eAAO,MAAM,eAAe;;;;EAAyB,CAAC;AAEtD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,YAAI,MAAM,EAAE,MAAM,EAAE,OAAO,CAAU,CAAC;AACvE,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AACjE,eAAO,MAAM,kBAAkB;;;;EAA+B,CAAC;AAC/D,eAAO,MAAM,aAAa;mBAClB,MAAM;mBACN,MAAM;oBACL,OAAO;CACuC,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,wBAAwB,YACnC,OAAO,EACP,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,UAAU,CACF,CAAC;AACX,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9E,4FAA4F;AAC5F,eAAO,MAAM,uBAAuB,WAAY,MAAM,KAAG,MAAM,IAAI,qBACD,CAAC;AAEnE,qGAAqG;AACrG,eAAO,MAAM,+BAA+B;;;;iBAI1C,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB,CAAC,KAAK,GAAG,MAAM;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,qBAAqB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAC9C,UAAU,EAAE,yBAAyB,EAAE,CAAC;IACxC,UAAU,EAAE,KAAK,CAAC;CACnB;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AA2BzC;;;;;GAKG;AACH,eAAO,MAAM,UAAU;;;;CAwBiB,CAAC;AA+BzC,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,IAAI,EAAE,OAAO,gBAAgB,EAAE,SAAS,CAAC;IACzC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC;CAClB;AA2CD,eAAO,MAAM,WAAW;;;;;;;;;;cAHP,QAAQ;;;;;;;;;;CAevB,CAAC;AAEH,6FAA6F;AAC7F,eAAO,MAAM,YAAY;;;;;;;kBAA4B,CAAC;AACtD,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG;KAAG,CAAC,IAAI,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;CAAE,CAAC,SAAS,CAAC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}