typegram - npm Package Compare versions

Comparing version 2.3.2 to 2.3.3

package.json

 {
   "name": "typegram",
-  "version": "2.3.2",
+  "version": "2.3.3",
   "description": "Type declarations for the Telegram API",
@@ -21,4 +21,4 @@ "main": "index.js",
   "devDependencies": {
-    "@types/node": "^14.6.0"
+    "@types/node": "^14.14.8"
   }
 }

README.md

@@ -5,2 +5,4 @@ # Types for the Telegram API
 
+It contains zero bytes of executable code.
+
 ## Installation
@@ -20,4 +22,15 @@
 
-The same pattern is used for various other types, too.
+In fact, this pattern is used for various types, namely:
 
+- `CallbackQuery`
+- `Chat`
+- `ChatFromGetChat`
+- `InlineKeyboardButton`
+- `KeyboardButton`
+- `Message`
+- `MessageEntity`
+- `Update`
+
+(Naturally, when the API specification is actually modelling types to be unions (e.g. `InputMedia`), this is reflected here as a union type, too.)
+
 ## Available Methods
@@ -34,2 +47,23 @@
 
+## Caveat with JSON-serialized objects
+
+Some methods of the Telegram API are expected to be called with JSON-serialized objects contained in a property of the payload, rather than an actual JSON payload.
+In other words, the objects are serialized twice—the first time in order to conform with the docs, and the second time when the payload is actually sent in the POST body to the API server.
+
+The most prominent example is the `reply_markup` property that appears in a number of different methods, but more than a dozen other properties like this can be found throughout the API.
+
+Strictly speaking, the `typegram` types do not reflect this accurately.
+Instead of using `string` (representing a serialized object) as the type, `typegram` uses the type of the object itself, thus ignoring the serialization step.
+For instance, instead of declaring `reply_markup: string`, it declares the property as `reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply` because that is what is supposed to be serialized to `string` before calling the respective method.
+
+This makes sense for two reasons.
+
+1. The goal of this library is to provide type safety.
+   However, the contents of a string cannot be typechecked for being valid JSON of the correct object.
+   As a result, we would be missing type safety if we would only model the properties as `string`.
+2. A common use case for this library is to pull the types into some wrapper code around the Telegram Bot API.
+   This wrapper code often does the necessary JSON serialization automatically for the required properties.
+   The consumer then does not need to care about which properties to serialize and which not.
+   Given that `typegram` refers to the objects themselves instead of their serialized strings, the wrapper code can now simply expose the `typegram` types to its consumers without having to transform them before.
+
 ## Using Promises
@@ -36,0 +70,0 @@

No alert changes

Improved metrics

Total package byte prevSize

202055

increased by1.16%

Lines of code

3392

increased by0.09%

Number of lines in readme file

84

increased by68%

No dependency changes