deprecate field-key in favor of field-name

Author: yoshuawuyts

Diff for: wit-0.3.0-draft/types.wit

@@ -107,12 +107,12 @@ interface types {
   /// This type enumerates the different kinds of errors that may occur when
   /// setting or appending to a `fields` resource.
   variant header-error {
-    /// This error indicates that a `field-key` or `field-value` was
+    /// This error indicates that a `field-name` or `field-value` was
     /// syntactically invalid when used with an operation that sets headers in a
     /// `fields`.
     invalid-syntax,
 
-    /// This error indicates that a forbidden `field-key` was used when trying
+    /// This error indicates that a forbidden `field-name` was used when trying
     /// to set a header in a `fields`.
     forbidden,
 
@@ -132,11 +132,11 @@ interface types {
     immutable,
   }
 
-  /// Field keys are always strings.
+  /// Field names are always strings.
   ///
   /// Field keys should always be treated as case insensitive by the `fields`
   /// resource for the purposes of equality checking.
-  type field-key = string;
+  type field-name = string;
 
   /// Field values should always be ASCII strings. However, in
   /// reality, HTTP implementations often have to interpret malformed values,
@@ -154,8 +154,7 @@ interface types {
   /// `set`, `append`, and `delete` operations will fail with
   /// `header-error.immutable`.
   ///
-  /// A `fields` resource should store `field-key`s and `field-value`s in their
-  /// original casing used to construct or mutate the `fields` resource. The `fields`
+  /// A `fields` resource should store `field-name`s and `field-value`s in their /// original casing used to construct or mutate the `fields` resource. The `fields`
   /// resource should use that original casing when serializing the fields for
   /// transport or when returning them from a method.
   resource fields {
@@ -181,44 +180,44 @@ interface types {
     /// An error result will be returned if any header or value was
     /// syntactically invalid, or if a header was forbidden.
     from-list: static func(
-      entries: list<tuple<field-key,field-value>>
+      entries: list<tuple<field-name,field-value>>
     ) -> result<fields, header-error>;
 
     /// Get all of the values corresponding to a key. If the key is not present
     /// in this `fields`, an empty list is returned. However, if the key is
     /// present but empty, this is represented by a list with one or more
     /// empty field-values present.
-    get: func(name: field-key) -> list<field-value>;
+    get: func(name: field-name) -> list<field-value>;
 
     /// Returns `true` when the key is present in this `fields`. If the key is
     /// syntactically invalid, `false` is returned.
-    has: func(name: field-key) -> bool;
+    has: func(name: field-name) -> bool;
 
     /// Set all of the values for a key. Clears any existing values for that
     /// key, if they have been set.
     ///
     /// Fails with `header-error.immutable` if the `fields` are immutable.
-    set: func(name: field-key, value: list<field-value>) -> result<_, header-error>;
+    set: func(name: field-name, value: list<field-value>) -> result<_, header-error>;
 
     /// Delete all values for a key. Does nothing if no values for the key
     /// exist.
     ///
     /// Fails with `header-error.immutable` if the `fields` are immutable.
-    delete: func(name: field-key) -> result<_, header-error>;
+    delete: func(name: field-name) -> result<_, header-error>;
 
     /// Delete all values for a key. Does nothing if no values for the key
     /// exist.
     ///
     /// Returns all values previously corresponding to the key, if any.
     ///
     /// Fails with `header-error.immutable` if the `fields` are immutable.
-    get-and-delete: func(name: field-key) -> result<list<field-value>, header-error>;
+    get-and-delete: func(name: field-name) -> result<list<field-value>, header-error>;
 
     /// Append a value for a key. Does not change or delete any existing
     /// values for that key.
     ///
     /// Fails with `header-error.immutable` if the `fields` are immutable.
-    append: func(name: field-key, value: field-value) -> result<_, header-error>;
+    append: func(name: field-name, value: field-value) -> result<_, header-error>;
 
     /// Retrieve the full set of keys and values in the Fields. Like the
     /// constructor, the list represents each key-value pair.
@@ -229,7 +228,7 @@ interface types {
     ///
     /// The keys and values are always returned in the original casing and in
     /// the order in which they will be serialized for transport.
-    entries: func() -> list<tuple<field-key,field-value>>;
+    entries: func() -> list<tuple<field-name,field-value>>;
 
     /// Make a deep copy of the Fields. Equivalent in behavior to calling the
     /// `fields` constructor on the return value of `entries`. The resulting

Diff for: wit/types.wit

@@ -124,12 +124,12 @@ interface types {
   /// setting or appending to a `fields` resource.
   @since(version = 0.2.0)
   variant header-error {
-    /// This error indicates that a `field-key` or `field-value` was
+    /// This error indicates that a `field-name` or `field-value` was
     /// syntactically invalid when used with an operation that sets headers in a
     /// `fields`.
     invalid-syntax,
 
-    /// This error indicates that a forbidden `field-key` was used when trying
+    /// This error indicates that a forbidden `field-name` was used when trying
     /// to set a header in a `fields`.
     forbidden,
 
@@ -138,11 +138,23 @@ interface types {
     immutable,
   }
 
+  /// Field names are always strings.
+  ///
+  /// Field keys should always be treated as case insensitive by the `fields`
+  /// resource for the purposes of equality checking.
+  @since(version = 0.2.1)
+  type field-name = field-key;
+
   /// Field keys are always strings.
   ///
   /// Field keys should always be treated as case insensitive by the `fields`
   /// resource for the purposes of equality checking.
+  /// 
+  /// # Deprecation
+  /// 
+  /// This type has been deprecated in favor of the `field-name` type.
   @since(version = 0.2.0)
+  @deprecate(since = 0.2.1)
   type field-key = string;
 
   /// Field values should always be ASCII strings. However, in
@@ -181,63 +193,66 @@ interface types {
     /// The tuple is a pair of the field key, represented as a string, and
     /// Value, represented as a list of bytes.
     ///
-    /// An error result will be returned if any `field-key` or `field-value` is
+    /// An error result will be returned if any `field-name` or `field-value` is
     /// syntactically invalid, or if a field is forbidden.
     @since(version = 0.2.0)
     from-list: static func(
-      entries: list<tuple<field-key,field-value>>
+      entries: list<tuple<field-name,field-value>>
     ) -> result<fields, header-error>;
 
     /// Get all of the values corresponding to a key. If the key is not present
     /// in this `fields` or is syntactically invalid, an empty list is returned.
     /// However, if the key is present but empty, this is represented by a list
     /// with one or more empty field-values present.
     @since(version = 0.2.0)
-    get: func(name: field-key) -> list<field-value>;
+    get: func(name: field-name) -> list<field-value>;
 
     /// Returns `true` when the key is present in this `fields`. If the key is
     /// syntactically invalid, `false` is returned.
     @since(version = 0.2.0)
-    has: func(name: field-key) -> bool;
+    has: func(name: field-name) -> bool;
 
     /// Set all of the values for a key. Clears any existing values for that
     /// key, if they have been set.
     ///
     /// Fails with `header-error.immutable` if the `fields` are immutable.
     ///
-    /// Fails with `header-error.invalid-syntax` if the `field-key` or any of
+    /// Fails with `header-error.invalid-syntax` if the `field-name` or any of
     /// the `field-value`s are syntactically invalid.
     @since(version = 0.2.0)
-    set: func(name: field-key, value: list<field-value>) -> result<_, header-error>;
+    set: func(name: field-name, value: list<field-value>) -> result<_, header-error>;
 
     /// Delete all values for a key. Does nothing if no values for the key
     /// exist.
     ///
     /// Fails with `header-error.immutable` if the `fields` are immutable.
     ///
-    /// Fails with `header-error.invalid-syntax` if the `field-key` is
+    /// Fails with `header-error.invalid-syntax` if the `field-name` is
     /// syntactically invalid.
     @since(version = 0.2.0)
-    delete: func(name: field-key) -> result<_, header-error>;
+    delete: func(name: field-name) -> result<_, header-error>;
 
     /// Append a value for a key. Does not change or delete any existing
     /// values for that key.
     ///
     /// Fails with `header-error.immutable` if the `fields` are immutable.
     ///
-    /// Fails with `header-error.invalid-syntax` if the `field-key` or
+    /// Fails with `header-error.invalid-syntax` if the `field-name` or
     /// `field-value` are syntactically invalid.
     @since(version = 0.2.0)
-    append: func(name: field-key, value: field-value) -> result<_, header-error>;
+    append: func(name: field-name, value: field-value) -> result<_, header-error>;
 
     /// Retrieve the full set of keys and values in the Fields. Like the
     /// constructor, the list represents each key-value pair.
     ///
     /// The outer list represents each key-value pair in the Fields. Keys
     /// which have multiple values are represented by multiple entries in this
     /// list with the same key.
+    ///
+    /// The keys and values are always returned in the original casing and in
+    /// the order in which they will be serialized for transport.
     @since(version = 0.2.0)
-    entries: func() -> list<tuple<field-key,field-value>>;
+    entries: func() -> list<tuple<field-name,field-value>>;
 
     /// Make a deep copy of the Fields. Equivalent in behavior to calling the
     /// `fields` constructor on the return value of `entries`. The resulting