@freecorps/ember-values 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FreeCorps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,12 @@
-# Temporary Holding Version
+# @freecorps/ember-values
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Ember validators (v.*), shapes, JSON Schema and order-preserving index key encoding.
+
+Part of [Ember](https://github.com/freecorps/ember), a Convex-style backend on Cloudflare Workers and Durable
+Objects. Source: [`packages/values`](https://github.com/freecorps/ember/tree/main/packages/values).
+
+```sh
+npm install @freecorps/ember-values
+```
+
+License: MIT.

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./shape.ts";
+export * from "./validators.ts";
+export * from "./validate.ts";
+export * from "./key.ts";
+export * from "./json.ts";
+export * from "./sql.ts";
+export * from "./rowdiff.ts";

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from "./shape.js";
+export * from "./validators.js";
+export * from "./validate.js";
+export * from "./key.js";
+export * from "./json.js";
+export * from "./sql.js";
+export * from "./rowdiff.js";

package/dist/json.d.ts

@@ -0,0 +1,25 @@
+import { type Shape } from "./shape.ts";
+export type JSONValue = null | boolean | number | string | JSONValue[] | {
+    [k: string]: JSONValue;
+};
+/** Standard base64 (with padding). `url` = base64url without padding. Pure JS: no Buffer/btoa. */
+export declare function bytesToBase64(bytes: Uint8Array, url?: boolean): string;
+export declare function base64ToBytes(s: string): Uint8Array;
+/** Ember value -> JSON-safe value (tags for bigint, bytes and non-finite / negative-zero numbers). */
+export declare function toJSONValue(x: unknown): JSONValue;
+/** Inverse of `toJSONValue`. */
+export declare function fromJSONValue(x: unknown): unknown;
+export declare const stringifyValue: (x: unknown) => string;
+export declare const parseValue: (s: string) => unknown;
+/**
+ * The canonical tagged JSON text of an Ember value (wire protocol, change log, `_json` column):
+ * `{"$int64":"…"}`, `{"$bytes":"<base64>"}`, `{"$float":"NaN"|"Infinity"|"-Infinity"|"-0"}`.
+ */
+export declare const encodeJson: (x: unknown) => string;
+/** Inverse of `encodeJson`. */
+export declare const decodeJson: (s: string) => unknown;
+/** Like `encodeJson` but with object keys sorted (stable cache keys, hashing). */
+export declare function encodeJsonStable(x: unknown): string;
+export type JsonSchema = Record<string, unknown>;
+/** JSON Schema (2020-12) of the wire form of `shape`. */
+export declare function toJsonSchema(shape: Shape): JsonSchema;

package/dist/json.js

@@ -0,0 +1,175 @@
+// JSON forms of Ember values.
+// - Wire/storage JSON: plain JSON with tagged objects for what JSON cannot carry:
+//     bigint -> {"$int64": "123"}, Uint8Array -> {"$bytes": "<base64>"},
+//     NaN / Infinity / -Infinity / -0 -> {"$float": "NaN" | "Infinity" | "-Infinity" | "-0"}.
+//   Field names starting with "$" are rejected by validation, so tags cannot collide with user data.
+// - JSON Schema of a Shape (for OpenAPI / tooling), describing the wire form.
+import { literalValue } from "./shape.js";
+import { isPlainObject } from "./validate.js";
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const B64_INDEX = new Map([...B64].map((c, i) => [c, i]));
+/** Standard base64 (with padding). `url` = base64url without padding. Pure JS: no Buffer/btoa. */
+export function bytesToBase64(bytes, url = false) {
+    let out = "";
+    let i = 0;
+    for (; i + 2 < bytes.length; i += 3) {
+        const n = (bytes[i] << 16) | (bytes[i + 1] << 8) | bytes[i + 2];
+        out += B64[n >> 18] + B64[(n >> 12) & 63] + B64[(n >> 6) & 63] + B64[n & 63];
+    }
+    const rest = bytes.length - i;
+    if (rest === 1) {
+        const n = bytes[i] << 16;
+        out += B64[n >> 18] + B64[(n >> 12) & 63] + "==";
+    }
+    else if (rest === 2) {
+        const n = (bytes[i] << 16) | (bytes[i + 1] << 8);
+        out += B64[n >> 18] + B64[(n >> 12) & 63] + B64[(n >> 6) & 63] + "=";
+    }
+    return url ? out.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "") : out;
+}
+export function base64ToBytes(s) {
+    const clean = s.replace(/-/g, "+").replace(/_/g, "/").replace(/=+$/, "");
+    if (!/^[A-Za-z0-9+/]*$/.test(clean) || clean.length % 4 === 1)
+        throw new Error("Invalid base64");
+    const out = new Uint8Array(Math.floor((clean.length * 3) / 4));
+    let o = 0;
+    for (let i = 0; i < clean.length; i += 4) {
+        const a = B64_INDEX.get(clean[i]);
+        const b = B64_INDEX.get(clean[i + 1]);
+        const c = i + 2 < clean.length ? B64_INDEX.get(clean[i + 2]) : 0;
+        const d = i + 3 < clean.length ? B64_INDEX.get(clean[i + 3]) : 0;
+        const n = (a << 18) | (b << 12) | (c << 6) | d;
+        out[o++] = n >> 16;
+        if (i + 2 < clean.length)
+            out[o++] = (n >> 8) & 255;
+        if (i + 3 < clean.length)
+            out[o++] = n & 255;
+    }
+    return out;
+}
+/** Ember value -> JSON-safe value (tags for bigint, bytes and non-finite / negative-zero numbers). */
+export function toJSONValue(x) {
+    switch (typeof x) {
+        case "string":
+        case "boolean":
+            return x;
+        case "number":
+            if (Number.isFinite(x) && !Object.is(x, -0))
+                return x;
+            return { $float: Number.isNaN(x) ? "NaN" : Object.is(x, -0) ? "-0" : x > 0 ? "Infinity" : "-Infinity" };
+        case "bigint":
+            return { $int64: x.toString() };
+        case "undefined":
+            return null;
+        case "object": {
+            if (x === null)
+                return null;
+            if (x instanceof Uint8Array)
+                return { $bytes: bytesToBase64(x) };
+            if (Array.isArray(x))
+                return x.map(toJSONValue);
+            const out = {};
+            for (const [k, item] of Object.entries(x))
+                if (item !== undefined)
+                    out[k] = toJSONValue(item);
+            return out;
+        }
+        default:
+            throw new Error(`Cannot convert ${typeof x} to JSON`);
+    }
+}
+/** Inverse of `toJSONValue`. */
+export function fromJSONValue(x) {
+    if (Array.isArray(x))
+        return x.map(fromJSONValue);
+    if (!isPlainObject(x))
+        return x;
+    const keys = Object.keys(x);
+    if (keys.length === 1) {
+        const k = keys[0];
+        const val = x[k];
+        if (k === "$int64" && typeof val === "string")
+            return BigInt(val);
+        if (k === "$bytes" && typeof val === "string")
+            return base64ToBytes(val);
+        if (k === "$float" && typeof val === "string") {
+            if (val === "-0")
+                return -0;
+            return Number(val);
+        }
+    }
+    const out = {};
+    for (const [k, item] of Object.entries(x))
+        out[k] = fromJSONValue(item);
+    return out;
+}
+export const stringifyValue = (x) => JSON.stringify(toJSONValue(x));
+export const parseValue = (s) => fromJSONValue(JSON.parse(s));
+/**
+ * The canonical tagged JSON text of an Ember value (wire protocol, change log, `_json` column):
+ * `{"$int64":"…"}`, `{"$bytes":"<base64>"}`, `{"$float":"NaN"|"Infinity"|"-Infinity"|"-0"}`.
+ */
+export const encodeJson = stringifyValue;
+/** Inverse of `encodeJson`. */
+export const decodeJson = parseValue;
+/** Like `encodeJson` but with object keys sorted (stable cache keys, hashing). */
+export function encodeJsonStable(x) {
+    const sort = (j) => Array.isArray(j) ? j.map(sort) : j && typeof j === "object" ? Object.fromEntries(Object.keys(j).sort().map((k) => [k, sort(j[k])])) : j;
+    return JSON.stringify(sort(toJSONValue(x)));
+}
+/** JSON Schema (2020-12) of the wire form of `shape`. */
+export function toJsonSchema(shape) {
+    switch (shape.kind) {
+        case "string":
+            return { type: "string" };
+        case "file":
+            return { type: "string", "x-ember-file": true };
+        case "id":
+            return { type: "string", "x-ember-id": shape.table };
+        case "number":
+            return {
+                anyOf: [
+                    { type: "number" },
+                    { type: "object", properties: { $float: { enum: ["NaN", "Infinity", "-Infinity", "-0"] } }, required: ["$float"], additionalProperties: false },
+                ],
+            };
+        case "int64":
+            return int64Schema;
+        case "boolean":
+            return { type: "boolean" };
+        case "null":
+            return { type: "null" };
+        case "bytes":
+            return { type: "object", properties: { $bytes: { type: "string", contentEncoding: "base64" } }, required: ["$bytes"], additionalProperties: false };
+        case "any":
+            return {};
+        case "literal": {
+            const val = literalValue(shape);
+            return typeof val === "bigint"
+                ? { type: "object", properties: { $int64: { const: val.toString() } }, required: ["$int64"], additionalProperties: false }
+                : { const: val };
+        }
+        case "array":
+            return { type: "array", items: toJsonSchema(shape.item) };
+        case "record":
+            return { type: "object", additionalProperties: toJsonSchema(shape.value), propertyNames: { pattern: "^[^$]" } };
+        case "object": {
+            const properties = {};
+            const required = [];
+            for (const [k, f] of Object.entries(shape.fields)) {
+                properties[k] = toJsonSchema(f.shape);
+                if (!f.optional)
+                    required.push(k);
+            }
+            return { type: "object", properties, required, additionalProperties: false };
+        }
+        case "union":
+            return { anyOf: shape.members.map(toJsonSchema) };
+    }
+}
+const int64Schema = {
+    type: "object",
+    properties: { $int64: { type: "string", pattern: "^-?[0-9]+$" } },
+    required: ["$int64"],
+    additionalProperties: false,
+};

package/dist/key.d.ts

@@ -0,0 +1,55 @@
+export declare const TAG: {
+    readonly end: 0;
+    readonly undefined: 1;
+    readonly null: 2;
+    readonly int64: 3;
+    readonly number: 4;
+    readonly false: 5;
+    readonly true: 6;
+    readonly string: 7;
+    readonly bytes: 8;
+    readonly array: 9;
+    readonly object: 10;
+};
+export type KeyValue = unknown;
+/** Encodes a tuple of values into an order-preserving byte string. */
+export declare function encodeKey(values: readonly unknown[]): Uint8Array;
+/** Encodes a single value (as a one-element tuple). */
+export declare const encodeValue: (x: unknown) => Uint8Array;
+/** Decodes a key produced by `encodeKey` back into its tuple. */
+export declare function decodeKey(key: Uint8Array): unknown[];
+/** memcmp: negative, zero or positive. */
+export declare function compareBytes(a: Uint8Array, b: Uint8Array): number;
+export declare function concatBytes(...parts: Uint8Array[]): Uint8Array;
+/** Exclusive upper bound of every key that starts with the tuple `prefix` (the encoded prefix ++ 0xFF). */
+export declare const prefixEnd: (prefix: Uint8Array) => Uint8Array;
+/** The smallest key strictly greater than `key` (key ++ 0x00). */
+export declare const keySuccessor: (key: Uint8Array) => Uint8Array;
+/** A half-open key range `[lo, hi)`. */
+export type KeyRange = {
+    lo: Uint8Array;
+    hi: Uint8Array;
+};
+export type LowerBound = {
+    op: "gt" | "gte";
+    value: unknown;
+};
+export type UpperBound = {
+    op: "lt" | "lte";
+    value: unknown;
+};
+/**
+ * The key range of an index read: equality on a prefix of the index fields, then optional lower/upper bounds on
+ * the next field. Bounds are on tuples, so `gt(x)` excludes every key whose field equals `x` regardless of the
+ * fields that follow.
+ */
+export declare function rangeFor(eq: readonly unknown[], lower?: LowerBound, upper?: UpperBound): KeyRange;
+/** Whether `key` lies in `[lo, hi)`. */
+export declare const inKeyRange: (key: Uint8Array, lo: Uint8Array, hi: Uint8Array) => boolean;
+/** Code-point order (which equals UTF-8 byte order); JS `<` compares UTF-16 units and differs above U+FFFF. */
+export declare function compareStrings(a: string, b: string): number;
+/**
+ * Logical comparison of two values in index order (the order `encodeKey` produces). Used for `.filter()`
+ * comparisons and anywhere values are ordered outside SQL.
+ */
+export declare function compareValues(a: unknown, b: unknown): number;