@geoprotocol/grc-20 0.2.0 → 0.2.2

package/dist/util/datetime.js

@@ -0,0 +1,245 @@
+/**
+ * RFC 3339 date/time parsing and formatting utilities.
+ *
+ * Converts between RFC 3339 formatted strings and GRC-20 internal representations:
+ * - Date: days since Unix epoch (1970-01-01) + offset in minutes
+ * - Time: microseconds since midnight + offset in minutes
+ * - Datetime: microseconds since Unix epoch + offset in minutes
+ */
+const MICROSECONDS_PER_SECOND = 1000000n;
+const MICROSECONDS_PER_MINUTE = 60n * MICROSECONDS_PER_SECOND;
+const MICROSECONDS_PER_HOUR = 60n * MICROSECONDS_PER_MINUTE;
+const MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000;
+/**
+ * Parses a timezone offset string (Z, +HH:MM, -HH:MM) and returns offset in minutes.
+ */
+function parseTimezoneOffset(offset) {
+    if (offset === "Z" || offset === "z") {
+        return 0;
+    }
+    const match = offset.match(/^([+-])(\d{2}):(\d{2})$/);
+    if (!match) {
+        throw new Error(`Invalid timezone offset: ${offset}`);
+    }
+    const sign = match[1] === "+" ? 1 : -1;
+    const hours = parseInt(match[2], 10);
+    const minutes = parseInt(match[3], 10);
+    if (hours > 23 || minutes > 59) {
+        throw new Error(`Invalid timezone offset: ${offset}`);
+    }
+    const totalMinutes = sign * (hours * 60 + minutes);
+    if (totalMinutes < -1440 || totalMinutes > 1440) {
+        throw new Error(`Timezone offset out of range [-24:00, +24:00]: ${offset}`);
+    }
+    return totalMinutes;
+}
+/**
+ * Formats an offset in minutes as a timezone string (Z, +HH:MM, -HH:MM).
+ */
+function formatTimezoneOffset(offsetMin) {
+    if (offsetMin === 0) {
+        return "Z";
+    }
+    const sign = offsetMin >= 0 ? "+" : "-";
+    const absOffset = Math.abs(offsetMin);
+    const hours = Math.floor(absOffset / 60);
+    const minutes = absOffset % 60;
+    return `${sign}${hours.toString().padStart(2, "0")}:${minutes.toString().padStart(2, "0")}`;
+}
+/**
+ * Parses fractional seconds string and returns microseconds.
+ */
+function parseFractionalSeconds(frac) {
+    if (!frac) {
+        return 0n;
+    }
+    // Pad or truncate to 6 digits (microseconds)
+    const padded = frac.padEnd(6, "0").slice(0, 6);
+    return BigInt(parseInt(padded, 10));
+}
+/**
+ * Formats microseconds as fractional seconds string, omitting if zero.
+ */
+function formatFractionalSeconds(us) {
+    if (us === 0n) {
+        return "";
+    }
+    // Convert to 6-digit string and trim trailing zeros
+    const str = us.toString().padStart(6, "0");
+    const trimmed = str.replace(/0+$/, "");
+    return `.${trimmed}`;
+}
+// =====================
+// DATE functions
+// =====================
+/**
+ * Parses an RFC 3339 date string (YYYY-MM-DD) and returns days since Unix epoch.
+ * Optionally accepts timezone offset suffix for date-with-offset format.
+ */
+export function parseDateRfc3339(dateStr) {
+    // Match YYYY-MM-DD with optional timezone offset
+    const match = dateStr.match(/^(\d{4})-(\d{2})-(\d{2})(?:(Z|[+-]\d{2}:\d{2}))?$/);
+    if (!match) {
+        throw new Error(`Invalid RFC 3339 date: ${dateStr}`);
+    }
+    const year = parseInt(match[1], 10);
+    const month = parseInt(match[2], 10);
+    const day = parseInt(match[3], 10);
+    const offsetStr = match[4];
+    // Validate month and day
+    if (month < 1 || month > 12) {
+        throw new Error(`Invalid month in date: ${dateStr}`);
+    }
+    if (day < 1 || day > 31) {
+        throw new Error(`Invalid day in date: ${dateStr}`);
+    }
+    // Calculate days since epoch using UTC Date
+    const date = Date.UTC(year, month - 1, day);
+    const days = Math.floor(date / MILLISECONDS_PER_DAY);
+    const offsetMin = offsetStr ? parseTimezoneOffset(offsetStr) : 0;
+    return { days, offsetMin };
+}
+/**
+ * Formats days since Unix epoch as RFC 3339 date string.
+ */
+export function formatDateRfc3339(days, offsetMin = 0) {
+    const date = new Date(days * MILLISECONDS_PER_DAY);
+    const year = date.getUTCFullYear();
+    const month = (date.getUTCMonth() + 1).toString().padStart(2, "0");
+    const day = date.getUTCDate().toString().padStart(2, "0");
+    const offset = formatTimezoneOffset(offsetMin);
+    return `${year}-${month}-${day}${offset}`;
+}
+// =====================
+// TIME functions
+// =====================
+/**
+ * Parses an RFC 3339 time string (HH:MM:SS[.ssssss][Z|+HH:MM]) and returns
+ * microseconds since midnight and offset in minutes.
+ */
+export function parseTimeRfc3339(timeStr) {
+    // Match HH:MM:SS[.fractional][timezone]
+    const match = timeStr.match(/^(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,6}))?(Z|[+-]\d{2}:\d{2})?$/);
+    if (!match) {
+        throw new Error(`Invalid RFC 3339 time: ${timeStr}`);
+    }
+    const hours = parseInt(match[1], 10);
+    const minutes = parseInt(match[2], 10);
+    const seconds = parseInt(match[3], 10);
+    const fractional = match[4];
+    const offsetStr = match[5];
+    // Validate ranges
+    if (hours > 23) {
+        throw new Error(`Invalid hours in time: ${timeStr}`);
+    }
+    if (minutes > 59) {
+        throw new Error(`Invalid minutes in time: ${timeStr}`);
+    }
+    if (seconds > 59) {
+        throw new Error(`Invalid seconds in time: ${timeStr}`);
+    }
+    const microseconds = parseFractionalSeconds(fractional);
+    const timeMicros = BigInt(hours) * MICROSECONDS_PER_HOUR +
+        BigInt(minutes) * MICROSECONDS_PER_MINUTE +
+        BigInt(seconds) * MICROSECONDS_PER_SECOND +
+        microseconds;
+    // Validate total is within day
+    if (timeMicros > 86399999999n) {
+        throw new Error(`Time exceeds maximum (23:59:59.999999): ${timeStr}`);
+    }
+    const offsetMin = offsetStr ? parseTimezoneOffset(offsetStr) : 0;
+    return { timeMicros, offsetMin };
+}
+/**
+ * Formats microseconds since midnight as RFC 3339 time string.
+ */
+export function formatTimeRfc3339(timeMicros, offsetMin = 0) {
+    const hours = Number(timeMicros / MICROSECONDS_PER_HOUR);
+    const remaining1 = timeMicros % MICROSECONDS_PER_HOUR;
+    const minutes = Number(remaining1 / MICROSECONDS_PER_MINUTE);
+    const remaining2 = remaining1 % MICROSECONDS_PER_MINUTE;
+    const seconds = Number(remaining2 / MICROSECONDS_PER_SECOND);
+    const microseconds = remaining2 % MICROSECONDS_PER_SECOND;
+    const hh = hours.toString().padStart(2, "0");
+    const mm = minutes.toString().padStart(2, "0");
+    const ss = seconds.toString().padStart(2, "0");
+    const frac = formatFractionalSeconds(microseconds);
+    const offset = formatTimezoneOffset(offsetMin);
+    return `${hh}:${mm}:${ss}${frac}${offset}`;
+}
+// =====================
+// DATETIME functions
+// =====================
+/**
+ * Parses an RFC 3339 datetime string and returns microseconds since Unix epoch
+ * and offset in minutes.
+ */
+export function parseDatetimeRfc3339(datetimeStr) {
+    // Match YYYY-MM-DDTHH:MM:SS[.fractional][timezone]
+    const match = datetimeStr.match(/^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,6}))?(Z|[+-]\d{2}:\d{2})?$/);
+    if (!match) {
+        throw new Error(`Invalid RFC 3339 datetime: ${datetimeStr}`);
+    }
+    const year = parseInt(match[1], 10);
+    const month = parseInt(match[2], 10);
+    const day = parseInt(match[3], 10);
+    const hours = parseInt(match[4], 10);
+    const minutes = parseInt(match[5], 10);
+    const seconds = parseInt(match[6], 10);
+    const fractional = match[7];
+    const offsetStr = match[8];
+    // Validate ranges
+    if (month < 1 || month > 12) {
+        throw new Error(`Invalid month in datetime: ${datetimeStr}`);
+    }
+    if (day < 1 || day > 31) {
+        throw new Error(`Invalid day in datetime: ${datetimeStr}`);
+    }
+    if (hours > 23) {
+        throw new Error(`Invalid hours in datetime: ${datetimeStr}`);
+    }
+    if (minutes > 59) {
+        throw new Error(`Invalid minutes in datetime: ${datetimeStr}`);
+    }
+    if (seconds > 59) {
+        throw new Error(`Invalid seconds in datetime: ${datetimeStr}`);
+    }
+    const offsetMin = offsetStr ? parseTimezoneOffset(offsetStr) : 0;
+    const microseconds = parseFractionalSeconds(fractional);
+    // Calculate epoch milliseconds in UTC
+    // Note: Date.UTC gives us milliseconds for the given UTC time components
+    const epochMs = Date.UTC(year, month - 1, day, hours, minutes, seconds);
+    // Convert to microseconds and add fractional component
+    // The epochMs is in UTC, but the datetime string represents local time with offset
+    // We need to subtract the offset to get the actual UTC time
+    const epochMicrosUTC = BigInt(epochMs) * 1000n + microseconds;
+    // Adjust for timezone offset: local time + offset = UTC
+    // So: UTC = local - offset
+    const offsetUs = BigInt(offsetMin) * MICROSECONDS_PER_MINUTE;
+    const epochMicros = epochMicrosUTC - offsetUs;
+    return { epochMicros, offsetMin };
+}
+/**
+ * Formats microseconds since Unix epoch as RFC 3339 datetime string.
+ */
+export function formatDatetimeRfc3339(epochMicros, offsetMin = 0) {
+    // Adjust for timezone offset: local time = UTC + offset
+    const offsetUs = BigInt(offsetMin) * MICROSECONDS_PER_MINUTE;
+    const localUs = epochMicros + offsetUs;
+    // Convert to milliseconds for Date constructor
+    const epochMs = Number(localUs / 1000n);
+    const microseconds = localUs % 1000000n;
+    // Handle negative microseconds (modulo can be negative in JS for negative numbers)
+    const microsecondsPositive = microseconds < 0n ? microseconds + 1000000n : microseconds;
+    const date = new Date(epochMs);
+    const year = date.getUTCFullYear();
+    const month = (date.getUTCMonth() + 1).toString().padStart(2, "0");
+    const day = date.getUTCDate().toString().padStart(2, "0");
+    const hours = date.getUTCHours().toString().padStart(2, "0");
+    const minutes = date.getUTCMinutes().toString().padStart(2, "0");
+    const seconds = date.getUTCSeconds().toString().padStart(2, "0");
+    const frac = formatFractionalSeconds(microsecondsPositive);
+    const offset = formatTimezoneOffset(offsetMin);
+    return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}${frac}${offset}`;
+}
+//# sourceMappingURL=datetime.js.map

package/dist/util/datetime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"datetime.js","sourceRoot":"","sources":["../../src/util/datetime.ts"],"names":[],"mappings":"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"}

package/dist/util/index.d.ts

@@ -1,2 +1,3 @@
 export { formatId, parseId, randomId, derivedUuid, derivedUuidAsync, derivedUuidFromString, uniqueRelationId, relationEntityId, } from "./id.js";
+export { parseDateRfc3339, formatDateRfc3339, parseTimeRfc3339, formatTimeRfc3339, parseDatetimeRfc3339, formatDatetimeRfc3339, } from "./datetime.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/util/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/util/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/util/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,eAAe,CAAC"}

package/dist/util/index.js

@@ -1,2 +1,3 @@
 export { formatId, parseId, randomId, derivedUuid, derivedUuidAsync, derivedUuidFromString, uniqueRelationId, relationEntityId, } from "./id.js";
+export { parseDateRfc3339, formatDateRfc3339, parseTimeRfc3339, formatTimeRfc3339, parseDatetimeRfc3339, formatDatetimeRfc3339, } from "./datetime.js";
 //# sourceMappingURL=index.js.map

package/dist/util/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/util/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/util/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,eAAe,CAAC"}

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@geoprotocol/grc-20",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "GRC-20 TypeScript library for binary property graph encoding/decoding",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/readme.md

@@ -100,6 +100,7 @@ import {
   EntityBuilder,        // Build entity values
   UpdateEntityBuilder,  // Build update operations
   RelationBuilder,      // Build relation operations
+  UpdateRelationBuilder,// Build relation update operations
 } from "@geoprotocol/grc-20";
 ```
 
@@ -114,16 +115,19 @@ const edit = new EditBuilder(editId)
     .text(propId, "value", languageId)
     .int64(propId, 42n, unitId)
     .float64(propId, 3.14, undefined)
+    .decimal(propId, { exponent: -2, mantissa: 1234n }, undefined)
     .bool(propId, true)
     .bytes(propId, new Uint8Array([1, 2, 3]))
     .point(propId, 40.7128, -74.006)
-    .date(propId, 19738, 0)                  // days since epoch, offset in minutes
-    .time(propId, 37800000000n, 0)           // microseconds since midnight, offset
-    .datetime(propId, 1705312200000000n, 0)  // microseconds since epoch, offset
+    .date(propId, "2024-01-15Z")             // RFC 3339 date
+    .time(propId, "10:30:00Z")               // RFC 3339 time
+    .datetime(propId, "2024-01-15T10:30:00Z")// RFC 3339 datetime
   )
   .updateEntity(entityId, u => u
     .setText(propId, "new value", undefined)
-    .unsetAll(propId)
+    .setInt64(propId, 100n, undefined)
+    .unsetText(propId, languageId)  // Unset specific language
+    .unsetAll(propId)               // Unset all values for property
   )
   .deleteEntity(entityId)
   .restoreEntity(entityId)
@@ -134,9 +138,54 @@ const edit = new EditBuilder(editId)
     .relationType(relationTypeId)
   )
   .deleteRelation(relationId)
+  .restoreRelation(relationId)
+  .createValueRef(valueRefId, entityId, propId, {
+    type: "text",
+    value: "Referenceable value"
+  })
   .build();
 ```
 
+### Ops (Functional API)
+
+`createEdit` defaults `id` to `randomId()` and `createdAt` to `0n` when omitted.
+
+```typescript
+import {
+  createEdit,
+  createEntity,
+  createRelation,
+  randomId,
+  properties,
+  relationTypes,
+} from "@geoprotocol/grc-20";
+
+const entityId = randomId();
+const authorId = randomId();
+
+const ops = [
+  createEntity({
+    id: entityId,
+    values: [
+      { property: properties.name(), value: { type: "text", value: "Alice" } },
+      { property: properties.description(), value: { type: "text", value: "A person" } },
+    ],
+  }),
+  createRelation({
+    id: randomId(),
+    relationType: relationTypes.types(),
+    from: entityId,
+    to: randomId(),
+  }),
+];
+
+const edit = createEdit({
+  name: "Create Alice",
+  author: authorId,
+  ops,
+});
+```
+
 ### Codec
 
 ```typescript
@@ -205,18 +254,57 @@ If using native ES modules without a bundler, add an import map for the WASM dep
 
 ```typescript
 import {
-  randomId,           // Generate random UUIDv4
-  parseId,            // Parse hex string to Id
-  formatId,           // Format Id as hex string
-  derivedUuid,        // Derive UUIDv8 from bytes (SHA-256)
+  randomId,             // Generate random UUIDv4
+  parseId,              // Parse hex string to Id
+  formatId,             // Format Id as hex string
+  derivedUuid,          // Derive UUIDv8 from bytes (SHA-256, sync)
+  derivedUuidAsync,     // Derive UUIDv8 from bytes (SHA-256, async)
   derivedUuidFromString,
-  uniqueRelationId,   // Derive relation ID from endpoints
-  relationEntityId,   // Derive entity ID from relation ID
-  idsEqual,           // Compare two Ids
-  NIL_ID,             // Zero UUID
+  uniqueRelationId,     // Derive relation ID from endpoints
+  relationEntityId,     // Derive entity ID from relation ID
+  idsEqual,             // Compare two Ids for equality
+  compareIds,           // Compare two Ids for ordering (-1, 0, 1)
+  NIL_ID,               // Zero UUID
 } from "@geoprotocol/grc-20";
 ```
 
+### Validation
+
+Validate values and positions before encoding:
+
+```typescript
+import { validateValue, validatePosition } from "@geoprotocol/grc-20";
+
+// Validate a value matches its declared type
+const result = validateValue(value, DataType.Text);
+if (!result.valid) {
+  console.error(result.error);
+}
+
+// Validate position string format
+const posResult = validatePosition("a0");
+if (!posResult.valid) {
+  console.error(posResult.error);
+}
+```
+
+### Data Types Reference
+
+| Type | TypeScript Representation |
+|------|---------------------------|
+| `BOOL` | `{ type: "bool", value: boolean }` |
+| `INT64` | `{ type: "int64", value: bigint, unit?: Id }` |
+| `FLOAT64` | `{ type: "float64", value: number, unit?: Id }` |
+| `DECIMAL` | `{ type: "decimal", exponent: number, mantissa: bigint, unit?: Id }` |
+| `TEXT` | `{ type: "text", value: string, language?: Id }` |
+| `BYTES` | `{ type: "bytes", value: Uint8Array }` |
+| `DATE` | `{ type: "date", value: string }` (RFC 3339, e.g. `"2024-01-15Z"`) |
+| `TIME` | `{ type: "time", value: string }` (RFC 3339, e.g. `"14:30:00Z"`) |
+| `DATETIME` | `{ type: "datetime", value: string }` (RFC 3339, e.g. `"2024-01-15T14:30:00Z"`) |
+| `SCHEDULE` | `{ type: "schedule", value: string }` (cron-like) |
+| `POINT` | `{ type: "point", lat: number, lon: number }` |
+| `EMBEDDING` | `{ type: "embedding", subType: EmbeddingSubType.Float32 \| EmbeddingSubType.Int8 \| EmbeddingSubType.Binary, data: number[] }` |
+
 ### Genesis IDs
 
 Well-known IDs from the Genesis Space: