naming-convention2: Timestamp and bigint in README

yoursunny · Jan 22, 2024 · a2ba1dd · a2ba1dd
1 parent 4ebab5b
commit a2ba1dd
Show file tree

Hide file tree

Showing 15 changed files with 86 additions and 24 deletions.
diff --git a/integ/browser-tests/package.json b/integ/browser-tests/package.json
@@ -30,7 +30,7 @@
     "puppeteer": "^21.7.0",
     "ts-loader": "^9.5.1",
     "tslib": "^2.6.2",
-    "type-fest": "^4.9.0",
+    "type-fest": "^4.10.0",
     "webpack": "^5.89.0",
     "webpack-cli": "^5.1.4",
     "webpack-dev-server": "^4.15.1"

diff --git a/mk/package.json b/mk/package.json
@@ -8,7 +8,7 @@
     "js-yaml": "^4.1.0",
     "readlink": "^3.0.0",
     "split2": "^4.2.0",
-    "type-fest": "^4.9.0"
+    "type-fest": "^4.10.0"
   },
   "dependencies": {
     "compare-versions": "6.1.0"

diff --git a/package.json b/package.json
@@ -13,7 +13,7 @@
     "test": "vitest",
     "typedoc": "bash mk/typedoc.sh"
   },
-  "packageManager": "pnpm@8.14.1",
+  "packageManager": "pnpm@8.14.2",
   "devDependencies": {
     "@types/node": "^20.11.5",
     "@types/wtfnode": "^0.7.3",

diff --git a/packages/autoconfig/package.json b/packages/autoconfig/package.json
@@ -43,6 +43,6 @@
     "@types/koa": "^2.14.0",
     "@types/node-fetch": "^2.6.11",
     "koa": "^2.15.0",
-    "type-fest": "^4.9.0"
+    "type-fest": "^4.10.0"
   }
 }
diff --git a/packages/l3face/package.json b/packages/l3face/package.json
@@ -37,7 +37,7 @@
     "retry": "^0.13.1",
     "streaming-iterables": "^8.0.1",
     "tslib": "^2.6.2",
-    "type-fest": "^4.9.0",
+    "type-fest": "^4.10.0",
     "typescript-event-target": "^1.1.0"
   },
   "devDependencies": {

diff --git a/packages/nac/package.json b/packages/nac/package.json
@@ -37,7 +37,7 @@
     "@yoursunny/asn1": "0.0.20200718",
     "mnemonist": "^0.39.7",
     "tslib": "^2.6.2",
-    "type-fest": "^4.9.0"
+    "type-fest": "^4.10.0"
   },
   "devDependencies": {
     "@ndn/repo": "workspace:*"

diff --git a/packages/naming-convention2/README.md b/packages/naming-convention2/README.md
@@ -8,14 +8,16 @@ The current format, sometimes known as **rev3 format**, is specified in [NDN-TR-
 It is supported in most other libraries and recommended for new applications.
 
 ```ts
-import { Keyword, Version, Segment, AltUri } from "@ndn/naming-convention2";
-// We also have ByteOffset, Timestamp, SequenceNum conventions,
-// as well as GenericNumber that puts NonNegativeInteger into GenericNameComponent.
+import { Keyword, Version, Segment, Timestamp, AltUri } from "@ndn/naming-convention2";
 
 // other imports for examples
 import { Name } from "@ndn/packet";
 import assert from "node:assert/strict";
+```
+
+## Basic Usage
 
+```ts
 // convention.create() returns a Component.
 let name = new Name(["A", Keyword.create("metadata")]);
 assert.equal(name.toString(), "/8=A/32=metadata");
@@ -43,22 +45,82 @@ assert.equal(Segment.parse(name.at(-1)), 0);
 assert.equal(name.at(-3).as(Keyword), "metadata");
 assert.equal(name.at(-2).as(Version), 3);
 assert.equal(name.at(-1).as(Segment), 0);
+```
+
+## Alternate URI Syntax
+
+This package exports **AltUri** that implements alternate URI syntax for the naming conventions.
+Make sure you are importing `AltUri` from this package, not from `@ndn/packet` package.
 
-// If you need alternate URI syntax, use AltUri.ofName() or AltUri.ofComponent().
-// Make sure you are importing AltUri from this package, not from @ndn/packet package.
+This feature is not in the regular `component.toString()` and `name.toString()` methods, because not every application would adopt this particular set of naming conventions.
+It is incorrect to interpret "54=%03" as "version 3" everywhere, because in some applications it could mean something completely different.
+Using `AltUri` from this package indicates you have adopted these naming conventions.
+
+```ts
+// Use AltUri.ofName() and AltUri.ofComponent() to print as alternate URI syntax.
 assert.equal(AltUri.ofName(name), "/A/32=metadata/v=3/seg=0");
 assert.equal(AltUri.ofComponent(name.at(2)), "v=3");
-// This feature is not in the regular component.toString() and name.toString() methods,
-// because not every application would adopt this particular set of naming conventions.
-// It is incorrect to interpret "54=%03" as "version 3" everywhere, because in some applications
-// it could mean something completely different.
-// Using AltUri from this package indicates you have adopted these naming conventions.
 
 // Use AltUri.parseName() and AltUri.parseComponent() to parse from alternate URI syntax.
 assert(AltUri.parseName("/A/32=metadata/v=3/seg=0").equals(name));
 assert(AltUri.parseComponent("v=3").equals(name.at(2)));
 ```
 
+## Timestamp Convention
+
+**Timestamp** can be constructed from either number or Date object.
+The number can be interpreted as either microseconds or milliseconds since Unix epoch.
+The name component is always encoded as microseconds since Unix epoch per specification.
+
+```ts
+// Creating from number, interpreted as microseconds since Unix epoch:
+const tsA = Timestamp.us.create(819170640000000);
+// Creating from number, interpreted as milliseconds since Unix epoch:
+const tsB = Timestamp.ms.create(819170640000);
+// Creating from Date object:
+const tsC = Timestamp.create(new Date("1995-12-17T03:24:00Z"));
+// They shall create the same name component:
+assert.ok(tsA.equals(tsB));
+assert.ok(tsA.equals(tsC));
+
+// Parsing into number as microseconds from Unix epoch:
+assert.equal(Timestamp.us.parse(tsB), 819170640000000);
+// Parsing into number as milliseconds from Unix epoch:
+assert.equal(Timestamp.ms.parse(tsC), 819170640000);
+// Call the Date constructor if you want a Date object:
+assert.deepEqual(new Date(Timestamp.ms.parse(tsA)), new Date("1995-12-17T03:24:00Z"));
+```
+
+As shown in the examples, you can use `.us` sub-convention for microseconds unit or use `.ms` sub-convention for milliseconds unit.
+The `Timestamp` convention is a shorthand for `Timestamp.ms`.
+
+## Number Conventions
+
+Number-based conventions, such as **Version** and **Segment**, can be constructed from and parsed into either number or bigint.
+
+```ts
+// Creating from number:
+const verA = Version.create(7);
+// Creating from bigint:
+const verB = Version.create(7n);
+// They shall create the same name component:
+assert.ok(verA.equals(verB));
+
+// Parsing into number:
+assert.equal(Version.parse(verB), 7);
+// Parsing into bigint:
+assert.equal(Version.big.parse(verB), 7n);
+```
+
+As shown in the examples, you can use `.big` sub-convention to parse as bigint.
+This is supported in Version, Segment, ByteOffset, SequenceNum, and GenericNumber.
+However, this is not supported in Timestamp.
+
+**GenericNumber** is a number-based convention that encodes a GenericNameComponent with NonNegativeInteger as TLV-VALUE.
+Despite not part of the naming convention specification, it is adopted by several NDN protocols, so that it is included for convenience.
+
+## Legacy rev2 Format
+
 This package also implements **rev2 format**, as specified in [NDN-TR-0022 revision 2](https://named-data.net/publications/techreports/ndn-tr-22-2-ndn-memo-naming-conventions/) and [Name Component Type Assignment rev17](https://redmine.named-data.net/projects/ndn-tlv/wiki/NameComponentType/17), published in 2019.
 Import `Segment2`, `ByteOffset2`, `Version2`, `Timestamp2`, `SequenceNum2`, `AltUri2` to access this format.
 You should not use this outdated and obsolete format in new applications, except for accessing old data.
diff --git a/packages/ndncert/package.json b/packages/ndncert/package.json
@@ -41,7 +41,7 @@
     "nodemailer": "^6.9.8",
     "p-timeout": "^6.1.2",
     "tslib": "^2.6.2",
-    "type-fest": "^4.9.0",
+    "type-fest": "^4.10.0",
     "typescript-event-target": "^1.1.0"
   },
   "devDependencies": {

diff --git a/packages/nfdmgmt/package.json b/packages/nfdmgmt/package.json
@@ -39,7 +39,7 @@
   "devDependencies": {
     "@ndn/l3face": "workspace:*",
     "@ndn/node-transport": "workspace:*",
-    "type-fest": "^4.9.0",
+    "type-fest": "^4.10.0",
     "typescript-event-target": "^1.1.0"
   }
 }
diff --git a/packages/node-transport/package.json b/packages/node-transport/package.json
@@ -27,7 +27,7 @@
     "@ndn/l3face": "workspace:*",
     "event-iterator": "^2.0.0",
     "tslib": "^2.6.2",
-    "type-fest": "^4.9.0",
+    "type-fest": "^4.10.0",
     "url-format-lax": "^2.0.0",
     "url-parse-lax": "^5.0.0"
   },

diff --git a/packages/packet/package.json b/packages/packet/package.json
@@ -31,7 +31,7 @@
     "buffer-compare": "^1.1.1",
     "mnemonist": "^0.39.7",
     "tslib": "^2.6.2",
-    "type-fest": "^4.9.0"
+    "type-fest": "^4.10.0"
   },
   "devDependencies": {
     "@types/buffer-compare": "^0.0.33"

diff --git a/packages/repo-api/package.json b/packages/repo-api/package.json
@@ -46,6 +46,6 @@
     "@types/tmp": "^0.2.6",
     "stream-mock": "^2.0.5",
     "tmp": "^0.2.1",
-    "type-fest": "^4.9.0"
+    "type-fest": "^4.10.0"
   }
 }
diff --git a/packages/segmented-object/package.json b/packages/segmented-object/package.json
@@ -45,6 +45,6 @@
     "@ndn/l3face": "workspace:*",
     "@ndn/repo-api": "workspace:*",
     "stream-mock": "^2.0.5",
-    "type-fest": "^4.9.0"
+    "type-fest": "^4.10.0"
   }
 }
diff --git a/packages/tlv/package.json b/packages/tlv/package.json
@@ -29,6 +29,6 @@
     "@ndn/util": "workspace:*",
     "mnemonist": "^0.39.7",
     "tslib": "^2.6.2",
-    "type-fest": "^4.9.0"
+    "type-fest": "^4.10.0"
   }
 }
diff --git a/packages/trust-schema/package.json b/packages/trust-schema/package.json
@@ -33,7 +33,7 @@
     "@ndn/util": "workspace:*",
     "mnemonist": "^0.39.7",
     "tslib": "^2.6.2",
-    "type-fest": "^4.9.0"
+    "type-fest": "^4.10.0"
   },
   "devDependencies": {
     "@ndn/repo": "workspace:*",