@systemfsoftware/hex-schema 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Lee
+
+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/dist/hex-schema.d.ts

@@ -0,0 +1,32 @@
+import { Schema } from 'effect';
+
+export declare const ColonHex: Schema.brand<Schema.transform<Schema.transform<Schema.refine<string, typeof Schema.String>, Schema.SchemaClass<string, string, never>>, Schema.brand<Schema.transform<Schema.refine<string, typeof Schema.String>, Schema.refine<string, typeof Schema.String>>, "HexString">>, "ColonHex">;
+
+export declare type ColonHex = Schema.Schema.Type<typeof ColonHex>;
+
+/**
+ * Composable hex-to-bytes schema. Compose any branded hex schema with
+ * this to produce a `Uint8Array` from that format:
+ *
+ * ```ts
+ * S.compose(PrefixedHex, HexBytes)  // Schema<Uint8Array, string>
+ * S.compose(ColonHex, HexBytes)     // Schema<Uint8Array, string>
+ * ```
+ */
+export declare const HexBytes: Schema.Schema<Uint8Array<ArrayBufferLike>, string, never>;
+
+export declare const HexString: Schema.brand<Schema.transform<Schema.refine<string, typeof Schema.String>, Schema.refine<string, typeof Schema.String>>, "HexString">;
+
+export declare type HexString = Schema.Schema.Type<typeof HexString>;
+
+export declare const PrefixedHex: Schema.brand<Schema.transform<Schema.refine<string, typeof Schema.String>, Schema.refine<string, typeof Schema.String>>, "PrefixedHex">;
+
+export declare type PrefixedHex = Schema.Schema.Type<typeof PrefixedHex>;
+
+export declare const StrictHex: Schema.refine<string, typeof Schema.String>;
+
+export declare const Uint8ArrayFromPrefixedHex: Schema.transform<Schema.refine<string, typeof Schema.String>, Schema.Schema<Uint8Array<ArrayBufferLike>, string, never>>;
+
+export declare type Uint8ArrayFromPrefixedHex = Schema.Schema.Type<typeof Uint8ArrayFromPrefixedHex>;
+
+export { }

package/dist/index.d.mts

@@ -0,0 +1,33 @@
+import { Schema } from "effect";
+//#region src/colon-hex.schema.d.ts
+declare const ColonHex: Schema.brand<Schema.transform<Schema.transform<Schema.refine<string, typeof Schema.String>, Schema.SchemaClass<string, string, never>>, Schema.brand<Schema.transform<Schema.refine<string, typeof Schema.String>, Schema.refine<string, typeof Schema.String>>, "HexString">>, "ColonHex">;
+type ColonHex = Schema.Schema.Type<typeof ColonHex>;
+//#endregion
+//#region src/hex-bytes.schema.d.ts
+/**
+ * Composable hex-to-bytes schema. Compose any branded hex schema with
+ * this to produce a `Uint8Array` from that format:
+ *
+ * ```ts
+ * S.compose(PrefixedHex, HexBytes)  // Schema<Uint8Array, string>
+ * S.compose(ColonHex, HexBytes)     // Schema<Uint8Array, string>
+ * ```
+ */
+declare const HexBytes: Schema.Schema<Uint8Array<ArrayBufferLike>, string, never>;
+//#endregion
+//#region src/hex-string.schema.d.ts
+declare const HexString: Schema.brand<Schema.transform<Schema.refine<string, typeof Schema.String>, Schema.refine<string, typeof Schema.String>>, "HexString">;
+type HexString = Schema.Schema.Type<typeof HexString>;
+//#endregion
+//#region src/prefixed-hex.schema.d.ts
+declare const PrefixedHex: Schema.brand<Schema.transform<Schema.brand<Schema.transform<Schema.refine<string, typeof Schema.String>, Schema.refine<string, typeof Schema.String>>, "HexString">, Schema.refine<string, typeof Schema.String>>, "PrefixedHex">;
+type PrefixedHex = Schema.Schema.Type<typeof PrefixedHex>;
+//#endregion
+//#region src/strict-hex.schema.d.ts
+declare const StrictHex: Schema.refine<string, typeof Schema.String>;
+//#endregion
+//#region src/uint8array-from-prefixed-hex.schema.d.ts
+declare const Uint8ArrayFromPrefixedHex: Schema.transform<Schema.brand<Schema.transform<Schema.brand<Schema.transform<Schema.refine<string, typeof Schema.String>, Schema.refine<string, typeof Schema.String>>, "HexString">, Schema.refine<string, typeof Schema.String>>, "PrefixedHex">, Schema.Schema<Uint8Array<ArrayBufferLike>, string, never>>;
+type Uint8ArrayFromPrefixedHex = Schema.Schema.Type<typeof Uint8ArrayFromPrefixedHex>;
+//#endregion
+export { ColonHex, HexBytes, HexString, PrefixedHex, StrictHex, Uint8ArrayFromPrefixedHex };

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import { Schema } from "effect";
+//#region src/colon-hex.schema.d.ts
+declare const ColonHex: Schema.brand<Schema.transform<Schema.transform<Schema.refine<string, typeof Schema.String>, Schema.SchemaClass<string, string, never>>, Schema.brand<Schema.transform<Schema.refine<string, typeof Schema.String>, Schema.refine<string, typeof Schema.String>>, "HexString">>, "ColonHex">;
+type ColonHex = Schema.Schema.Type<typeof ColonHex>;
+//#endregion
+//#region src/hex-bytes.schema.d.ts
+/**
+ * Composable hex-to-bytes schema. Compose any branded hex schema with
+ * this to produce a `Uint8Array` from that format:
+ *
+ * ```ts
+ * S.compose(PrefixedHex, HexBytes)  // Schema<Uint8Array, string>
+ * S.compose(ColonHex, HexBytes)     // Schema<Uint8Array, string>
+ * ```
+ */
+declare const HexBytes: Schema.Schema<Uint8Array<ArrayBufferLike>, string, never>;
+//#endregion
+//#region src/hex-string.schema.d.ts
+declare const HexString: Schema.brand<Schema.transform<Schema.refine<string, typeof Schema.String>, Schema.refine<string, typeof Schema.String>>, "HexString">;
+type HexString = Schema.Schema.Type<typeof HexString>;
+//#endregion
+//#region src/prefixed-hex.schema.d.ts
+declare const PrefixedHex: Schema.brand<Schema.transform<Schema.refine<string, typeof Schema.String>, Schema.refine<string, typeof Schema.String>>, "PrefixedHex">;
+type PrefixedHex = Schema.Schema.Type<typeof PrefixedHex>;
+//#endregion
+//#region src/strict-hex.schema.d.ts
+declare const StrictHex: Schema.refine<string, typeof Schema.String>;
+//#endregion
+//#region src/uint8array-from-prefixed-hex.schema.d.ts
+declare const Uint8ArrayFromPrefixedHex: Schema.transform<Schema.refine<string, typeof Schema.String>, Schema.Schema<Uint8Array<ArrayBufferLike>, string, never>>;
+type Uint8ArrayFromPrefixedHex = Schema.Schema.Type<typeof Uint8ArrayFromPrefixedHex>;
+//#endregion
+export { ColonHex, HexBytes, HexString, PrefixedHex, StrictHex, Uint8ArrayFromPrefixedHex };

package/dist/index.mjs

@@ -0,0 +1,70 @@
+import { Encoding, Schema, pipe } from "effect";
+//#region src/strict-hex.schema.ts
+const StrictHex = Schema.String.pipe(Schema.pattern(/^[0-9a-f]*$/), Schema.annotations({
+	arbitrary: () => (fc) => fc.hexaString(),
+	identifier: "StrictHex",
+	description: "A lowercase hexadecimal string with no prefix",
+	title: "Strict Hex String"
+}));
+//#endregion
+//#region src/hex-string.schema.ts
+const HexString = pipe(Schema.transform(Schema.String.pipe(Schema.pattern(/^(0x)?[0-9a-fA-F]*$/), Schema.annotations({ arbitrary: () => (fc) => fc.stringMatching(/^(0x)?[0-9a-fA-F]*$/) })), StrictHex, {
+	decode: (hex) => (hex.startsWith("0x") ? hex.slice(2) : hex).toLowerCase(),
+	encode: (s) => s
+}), Schema.annotations({
+	identifier: "HexString",
+	description: "A string representing hexadecimal data, with or without the 0x prefix",
+	title: "Hex String"
+}), Schema.brand("HexString"));
+//#endregion
+//#region src/colon-hex.schema.ts
+const hexToColon = (hex) => (hex.match(/.{1,2}/g) ?? []).map((byte) => byte.toUpperCase()).join(":");
+const ColonHex = pipe(Schema.compose(Schema.transform(Schema.String.pipe(Schema.pattern(/^([0-9A-Fa-f]{1,2}(:[0-9A-Fa-f]{1,2})*)?$/), Schema.annotations({ arbitrary: () => (fc) => fc.hexaString().map(hexToColon) })), Schema.encodedSchema(HexString), {
+	strict: true,
+	decode: (colon) => colon.replaceAll(":", ""),
+	encode: hexToColon
+}), HexString), Schema.annotations({
+	identifier: "ColonHex",
+	description: "Colon-separated uppercase hex bytes — the fingerprint format",
+	title: "Colon-Separated Hex String"
+}), Schema.brand("ColonHex"));
+//#endregion
+//#region src/hex-bytes.schema.ts
+/**
+* Composable hex-to-bytes schema. Compose any branded hex schema with
+* this to produce a `Uint8Array` from that format:
+*
+* ```ts
+* S.compose(PrefixedHex, HexBytes)  // Schema<Uint8Array, string>
+* S.compose(ColonHex, HexBytes)     // Schema<Uint8Array, string>
+* ```
+*/
+const HexBytes = Schema.Uint8ArrayFromHex.pipe(Schema.annotations({
+	identifier: "HexBytes",
+	description: "Uint8Array encoded as a lowercase hex string — compose with any hex schema",
+	title: "Hex Bytes"
+}));
+//#endregion
+//#region src/prefixed-hex.schema.ts
+const PrefixedHex = pipe(Schema.transform(Schema.String.pipe(Schema.pattern(/^0x[0-9a-f]*$/), Schema.annotations({ arbitrary: () => (fc) => fc.hexaString().map((hex) => `0x${hex}`) })), StrictHex, {
+	strict: true,
+	decode: (fromA) => fromA.slice(2),
+	encode: (toI) => `0x${toI}`
+}), Schema.annotations({
+	identifier: "PrefixedHex",
+	description: "A 0x-prefixed hex string on the wire — decodes to a plain lowercase hex string",
+	title: "Prefixed Hex String"
+}), Schema.brand("PrefixedHex"));
+//#endregion
+//#region src/uint8array-from-prefixed-hex.schema.ts
+const Uint8ArrayFromPrefixedHex = pipe(Schema.transform(Schema.String.pipe(Schema.pattern(/^0x(?:[0-9a-f]{2})*$/), Schema.annotations({ arbitrary: () => (fc) => fc.uint8Array().map((bytes) => `0x${Encoding.encodeHex(bytes)}`) })), HexBytes, {
+	strict: true,
+	decode: (prefixed) => prefixed.slice(2),
+	encode: (hex) => `0x${hex}`
+}), Schema.annotations({
+	identifier: "Uint8ArrayFromPrefixedHex",
+	description: "Uint8Array encoded as a 0x-prefixed hex string",
+	title: "Uint8Array from Prefixed Hex"
+}));
+//#endregion
+export { ColonHex, HexBytes, HexString, PrefixedHex, StrictHex, Uint8ArrayFromPrefixedHex };

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@systemfsoftware/hex-schema",
+  "license": "MIT",
+  "version": "0.1.0",
+  "author": "Ryan Lee <drdgvhbh@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/systemfsoftware/systemfsoftware.git",
+    "directory": "packages/hex-schema"
+  },
+  "homepage": "https://github.com/systemfsoftware/systemfsoftware/tree/main/packages/hex-schema#readme",
+  "bugs": "https://github.com/systemfsoftware/systemfsoftware/issues",
+  "description": "Effect Schema definitions for hexadecimal wire formats — strict, colon-delimited, prefixed, and byte-level schemas with branded types.",
+  "keywords": [
+    "effect",
+    "effect-ts",
+    "schema",
+    "codec",
+    "hex",
+    "hexstring",
+    "branded-types",
+    "typescript"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/hex-schema.d.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "effect": "^3.22.0"
+  },
+  "devDependencies": {
+    "@effect/vitest": "0.30.0",
+    "@microsoft/api-extractor": "^7.58.7",
+    "@types/node": "^24",
+    "fast-check": "^3",
+    "rimraf": "^6.1.3",
+    "tsdown": "^0.22.9",
+    "vitest": "^4",
+    "@systemfsoftware/effect-schema-law": "^0.1.0",
+    "@systemfsoftware/effect-schema-vite": "^0.1.0",
+    "@systemfsoftware/tsconfig": "^1.0.0",
+    "@systemfsoftware/oxlint-config": "^0.1.0",
+    "@systemfsoftware/vitest-config": "^0.1.0"
+  },
+  "peerDependencies": {
+    "effect": "*"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit --incremental",
+    "test": "vitest run",
+    "api:check": "api-extractor run",
+    "api:update": "api-extractor run --local",
+    "lint": "oxlint . ${AGENT:+--format=unix --quiet}"
+  }
+}