@peers-app/peers-sdk 0.26.5 → 0.27.0

package/dist/types/field-type.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+/** The value types a Peers IR field can have. */
 export declare enum FieldType {
     id = "id",
     string = "string",
@@ -9,6 +10,37 @@ export declare enum FieldType {
     blob = "blob",
     any = "any"
 }
+/**
+ * One field in Peers IR: a table column, a tool input or output, an event payload field, or
+ * (without `name`) an observable's value.
+ *
+ * The Runtime checks `type`, `optional`, and `isArray` on table rows, tool arguments, and event
+ * payloads (an observable's value, against its `valueType`). `fields` and `enumValues` describe
+ * the value further, for the models that call tools and for generated types; the package's own
+ * schema enforces them.
+ *
+ * A field has one empty value: missing. The Runtime removes an optional field that is `null` or
+ * `undefined` (a field with a default gets the default instead), stores it as SQL NULL, and
+ * reads it back unset.
+ */
+export interface IField {
+    name: string;
+    description?: string;
+    type: FieldType;
+    defaultValue?: any;
+    /** The value may be empty: missing, `undefined`, or `null`, all read back as missing. */
+    optional?: boolean;
+    /** The value is an array of `type`; `fields`, `enumValues` describe each element. */
+    isArray?: boolean;
+    subType?: string;
+    /** An object's own fields. Absent: any object. Only on `object`; other keys may be present. */
+    fields?: IField[];
+    /** The only values allowed: strings, numbers, or booleans matching `type` (any of them on `any`). */
+    enumValues?: (string | number | boolean)[];
+}
+/** A field's shape without its name: an observable's value. */
+export type IFieldShape = Omit<IField, "name">;
+/** Zod schema for {@link IField}, used where rows store field lists. */
 export declare const fieldSchema: z.ZodObject<{
     name: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
@@ -17,21 +49,6 @@ export declare const fieldSchema: z.ZodObject<{
     optional: z.ZodOptional<z.ZodBoolean>;
     isArray: z.ZodOptional<z.ZodBoolean>;
     subType: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    name: string;
-    type: FieldType;
-    optional?: boolean | undefined;
-    description?: string | undefined;
-    defaultValue?: any;
-    isArray?: boolean | undefined;
-    subType?: string | undefined;
-}, {
-    name: string;
-    type: FieldType;
-    optional?: boolean | undefined;
-    description?: string | undefined;
-    defaultValue?: any;
-    isArray?: boolean | undefined;
-    subType?: string | undefined;
-}>;
-export type IField = z.infer<typeof fieldSchema>;
+    fields: z.ZodOptional<z.ZodLazy<z.ZodArray<z.ZodType<IField>>>>;
+    enumValues: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+}, "strip", z.ZodTypeAny, IField, IField>;

package/dist/types/field-type.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.fieldSchema = exports.FieldType = void 0;
 const zod_1 = require("zod");
 //export type FieldType = 'id' | 'string' | 'number' | 'boolean' | 'Date' | 'object' | 'blob' | 'any';
+/** The value types a Peers IR field can have. */
 var FieldType;
 (function (FieldType) {
     FieldType["id"] = "id";
@@ -14,6 +15,7 @@ var FieldType;
     FieldType["blob"] = "blob";
     FieldType["any"] = "any";
 })(FieldType || (exports.FieldType = FieldType = {}));
+/** Zod schema for {@link IField}, used where rows store field lists. */
 exports.fieldSchema = zod_1.z.object({
     name: zod_1.z.string(),
     description: zod_1.z.string().optional(),
@@ -21,6 +23,7 @@ exports.fieldSchema = zod_1.z.object({
     defaultValue: zod_1.z.any().optional(),
     optional: zod_1.z.boolean().optional(),
     isArray: zod_1.z.boolean().optional(),
-    // enumValues: z.array(z.string()).optional(),
     subType: zod_1.z.string().optional(),
+    fields: zod_1.z.lazy(() => zod_1.z.array(exports.fieldSchema)).optional(),
+    enumValues: zod_1.z.array(zod_1.z.union([zod_1.z.string(), zod_1.z.number(), zod_1.z.boolean()])).optional(),
 });

package/dist/types/zod-types.d.ts

@@ -1,8 +1,17 @@
 import { z } from "zod";
 export { z } from "zod";
+/** Any plain object, with every key kept. */
 export declare const zodAnyObject: z.ZodObject<{}, "strip", z.ZodAny, z.objectOutputType<{}, z.ZodAny, "strip">, z.objectInputType<{}, z.ZodAny, "strip">>;
+/** Any plain object or any array. */
 export declare const zodAnyObjectOrArray: z.ZodUnion<[z.ZodObject<{}, "strip", z.ZodAny, z.objectOutputType<{}, z.ZodAny, "strip">, z.objectInputType<{}, z.ZodAny, "strip">>, z.ZodArray<z.ZodAny, "many">]>;
+/**
+ * A 25-character peer id from `newid()`. Marked as {@link FieldType.id}, so `schemaToFields`
+ * records the field as an id.
+ */
 export declare const zodPeerId: z.ZodEffects<z.ZodString, string, string>;
+/** Any zod object schema. */
 export type ZodObjectType = z.ZodObject<any>;
+/** Any zod array schema. */
 export type ZodArrayType = z.ZodArray<any>;
+/** Any zod object or array schema. */
 export type ZodAnyObjectOrArrayType = ZodArrayType | ZodObjectType;

package/dist/types/zod-types.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.zodPeerId = exports.zodAnyObjectOrArray = exports.zodAnyObject = exports.z = void 0;
 const zod_1 = require("zod");
-const utils_1 = require("../utils");
+const peer_id_1 = require("../peer-id");
 const field_type_1 = require("./field-type");
 // Re-export zod so consumers import it via peers-sdk. This guarantees every
 // schema in the graph is built with the same zod instance that peers-sdk's
@@ -10,10 +10,16 @@ const field_type_1 = require("./field-type");
 // matters because those helpers reach into zod internals (`_def`, shape).
 var zod_2 = require("zod");
 Object.defineProperty(exports, "z", { enumerable: true, get: function () { return zod_2.z; } });
+/** Any plain object, with every key kept. */
 exports.zodAnyObject = zod_1.z.object({}).catchall(zod_1.z.any());
+/** Any plain object or any array. */
 exports.zodAnyObjectOrArray = zod_1.z.union([exports.zodAnyObject, zod_1.z.array(zod_1.z.any())]);
+/**
+ * A 25-character peer id from `newid()`. Marked as {@link FieldType.id}, so `schemaToFields`
+ * records the field as an id.
+ */
 exports.zodPeerId = zod_1.z.string().refine((value) => {
-    return (0, utils_1.isid)(value);
+    return (0, peer_id_1.isid)(value);
 }, {
     message: "Invalid peer id, it must be a 25 character alphanumeric string",
 });

package/dist/utils.d.ts

@@ -1,30 +1,6 @@
 import type { ITableMetaData } from "./data/orm";
 import { type IDeviceConnection } from "./types/peer-device";
-/** Builds a random string of base-36 characters with unbiased distribution (tweetnacl-backed). */
-export declare function cryptoRandomString(length: number): string;
-/**
- * Creates a new 25-character peer id: base-36 time prefix (10 chars) + random suffix (15 chars).
- * Sort order correlates with creation time. Use {@link isid} to validate user-provided values.
- */
-export declare function newid(): string;
-/** Lexicographic lower bound for valid peer ids (epoch). */
-export declare const MIN_ID: string;
-/** Lexicographic upper bound for valid peer ids (far future). */
-export declare const MAX_ID: string;
-/**
- * Returns whether `id` is a 25-char base-36 string whose embedded time is not in the future (5 min skew allowed).
- * @param id Candidate id (coerced to string)
- */
-export declare function isid(id: any): boolean;
-/** Returns the `Date.now()`-compatible millisecond time encoded in the first 10 base-36 characters of a peer id. */
-export declare function idTime(id: string): number;
-/** Interprets a peer id’s time prefix as a `Date` (see {@link idTime}). */
-export declare function idDate(id: string): Date;
-/**
- * Returns the 15-character random suffix of a peer id as two base-36 integers so large values stay exact in JS.
- * @param id A 25-character peer id from {@link newid}
- */
-export declare function idRandNums(id: string): [number, number];
+export { cryptoRandomString, idDate, idRandNums, idTime, isid, MAX_ID, MIN_ID, newid, } from "./peer-id";
 /** Fast non-cryptographic 32-bit string hash (sign-insensitive) for display keys and bucketing. */
 export declare function simpleHash(str: string): number;
 /** Like TypeScript’s `Partial` for specific keys: required keys in `K` become optional. */

package/dist/utils.js

@@ -1,12 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TIMESTAMP_REANCHOR_THRESHOLD_MS = exports.moneyFormatter = exports.MAX_ID = exports.MIN_ID = void 0;
-exports.cryptoRandomString = cryptoRandomString;
-exports.newid = newid;
-exports.isid = isid;
-exports.idTime = idTime;
-exports.idDate = idDate;
-exports.idRandNums = idRandNums;
+exports.TIMESTAMP_REANCHOR_THRESHOLD_MS = exports.moneyFormatter = exports.newid = exports.MIN_ID = exports.MAX_ID = exports.isid = exports.idTime = exports.idRandNums = exports.idDate = exports.cryptoRandomString = void 0;
 exports.simpleHash = simpleHash;
 exports.simpleObjectHash = simpleObjectHash;
 exports.deterministicPvarId = deterministicPvarId;
@@ -27,89 +21,15 @@ const _ = require("lodash");
 const nacl = require("tweetnacl");
 const peer_device_1 = require("./types/peer-device");
 const stableStringify = require("fast-json-stable-stringify");
-/** Builds a random string of base-36 characters with unbiased distribution (tweetnacl-backed). */
-function cryptoRandomString(length) {
-    let s = "";
-    let r = nacl.randomBytes(length + 6);
-    let i = 0;
-    while (s.length < length) {
-        if (i >= r.length) {
-            r = nacl.randomBytes(length - s.length);
-            i = 0;
-        }
-        const n = r[i];
-        i++;
-        if (n >= 252) {
-            // we don't want to bias the characters generated so only consider the range of numbers that spread evenly between factors of 36
-            // we exclude 252, 253, 254, and 255 because it would bias towards '0', '1', '2', and '3' respectively
-            continue;
-        }
-        s += (n % 36).toString(36);
-    }
-    return s.substring(0, length);
-}
-/**
- * Creates a new 25-character peer id: base-36 time prefix (10 chars) + random suffix (15 chars).
- * Sort order correlates with creation time. Use {@link isid} to validate user-provided values.
- */
-function newid() {
-    // modeled after mongo ids, timestamp + counter + random but we're going to skip counter and have bigger random
-    // people can switch to using a counter + random later if they want (or do something else with the random part).
-    // This id is going to be a 128 bit number so it fits naturally into memory.
-    // 2 ** 128 ~= 3.4e38 is the maximum it can be
-    // For efficient transmission, storage, presentation, and usage we're going to represent this number with base 36 [0-9a-z]
-    // (3.4e38).toString(36) == "f55n5nmuuaw00000000000000", this is our max in base 36, 25 characters
-    // Date.now() =~ 1625282091498
-    // but we're dealing in base 36 not base 10
-    // (1625282091498).toString(36) == "kqn6zrvu" (length 8)
-    // Number.parseInt("zzzzzzzz", 36) == 2821109907455 == year 2059.  Way too soon so going up to 9 characters
-    // Number.parseInt("zzzzzzzzz", 36) == 101559956668415 == year 5188.
-    // but the max size of 9 left most can only be "f55n5nmuu" == 42720753566838 == year 3323.  That could still work but only ~ 1300 years
-    // that leaves 16 characters to represent a random number to prevent collisions each millisecond, 36 ** 16 ~= 8e24
-    // Allocating one more character to the time and one less to the random number to avoid hitting max time in any conceivable future
-    // now our max time is new Date(Number.parseInt('f55n5nmuua',36)) == +050705-08-09T23:40:06.178Z. 50k years from now.
-    // We still have 15 chars for our random number. 36 ** 15 ~= 2e23
-    // That is still a very large number and the chance of a collision should be so small as to be effectively globally unique
-    // and certainly unique in any group's database.
-    const time = Date.now().toString(36).padStart(10, "0"); // e.g: "00kq6xh45f", length == 10
-    return time + cryptoRandomString(15);
-}
-/** Lexicographic lower bound for valid peer ids (epoch). */
-exports.MIN_ID = "0".repeat(25); // 1970
-/** Lexicographic upper bound for valid peer ids (far future). */
-exports.MAX_ID = `f55n5nmuua${"z".repeat(15)}`; // 50k years from now
-/**
- * Returns whether `id` is a 25-char base-36 string whose embedded time is not in the future (5 min skew allowed).
- * @param id Candidate id (coerced to string)
- */
-function isid(id) {
-    id = String(id);
-    const idMatch = Boolean(/^[0-9a-z]{25}$/i.exec(id));
-    if (idMatch) {
-        // only consider ids valid if they are less than current time (with 5 min buffer)
-        // This is to prevent people from making ids with times in the future to get them to always show up as the "newest" item and/or prematurely claim ids
-        return idTime(id) < Date.now() + 300000;
-    }
-    return false;
-}
-/** Returns the `Date.now()`-compatible millisecond time encoded in the first 10 base-36 characters of a peer id. */
-function idTime(id) {
-    const time36 = id.substr(0, 10);
-    return Number.parseInt(time36, 36);
-}
-/** Interprets a peer id’s time prefix as a `Date` (see {@link idTime}). */
-function idDate(id) {
-    return new Date(idTime(id));
-}
-/**
- * Returns the 15-character random suffix of a peer id as two base-36 integers so large values stay exact in JS.
- * @param id A 25-character peer id from {@link newid}
- */
-function idRandNums(id) {
-    const numPart1 = id.substr(10, 8);
-    const numPart2 = id.substr(18, 7);
-    return [Number.parseInt(numPart1, 36), Number.parseInt(numPart2, 36)];
-}
+var peer_id_1 = require("./peer-id");
+Object.defineProperty(exports, "cryptoRandomString", { enumerable: true, get: function () { return peer_id_1.cryptoRandomString; } });
+Object.defineProperty(exports, "idDate", { enumerable: true, get: function () { return peer_id_1.idDate; } });
+Object.defineProperty(exports, "idRandNums", { enumerable: true, get: function () { return peer_id_1.idRandNums; } });
+Object.defineProperty(exports, "idTime", { enumerable: true, get: function () { return peer_id_1.idTime; } });
+Object.defineProperty(exports, "isid", { enumerable: true, get: function () { return peer_id_1.isid; } });
+Object.defineProperty(exports, "MAX_ID", { enumerable: true, get: function () { return peer_id_1.MAX_ID; } });
+Object.defineProperty(exports, "MIN_ID", { enumerable: true, get: function () { return peer_id_1.MIN_ID; } });
+Object.defineProperty(exports, "newid", { enumerable: true, get: function () { return peer_id_1.newid; } });
 /** Fast non-cryptographic 32-bit string hash (sign-insensitive) for display keys and bucketing. */
 function simpleHash(str) {
     let hash = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peers-app/peers-sdk",
-  "version": "0.26.5",
+  "version": "0.27.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/peers-app/peers-sdk.git"
@@ -9,8 +9,14 @@
   "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "peers-package": "bin/peers-package.js"
+  },
   "files": [
-    "dist"
+    "dist",
+    "define",
+    "testing",
+    "bin"
   ],
   "publishConfig": {
     "access": "public"
@@ -61,6 +67,7 @@
     "@types/moment-timezone": "^0.5.30",
     "@types/node": "^22.4.0",
     "better-sqlite3": "^11.8.1",
+    "esbuild": "^0.28.2",
     "jest": "^29.7.0",
     "ts-jest": "^29.2.5",
     "typescript": "^5.8.3"

package/testing/package.json

@@ -0,0 +1,4 @@
+{
+  "main": "../dist/testing/index.js",
+  "types": "../dist/testing/index.d.ts"
+}