open-index/open-npm huggingface dataset:
npm package: @grounds/core
Description: Low-level Relish binary serialization for TypeScript
Author: Bojan Rajkovic
Latest version: 1.0.0

# @grounds/core

Low-level Relish binary serialization for TypeScript.

## Installation

```bash
npm install @grounds/core
```

## Usage

### Encoding

```typescript
import { encode, TypeCode } from "@grounds/core";

// Encode primitive values
const nullResult = encode({ type: TypeCode.Null, value: null });
const boolResult = encode({ type: TypeCode.Bool, value: true });
const u32Result = encode({ type: TypeCode.U32, value: 42 });
const stringResult = encode({ type: TypeCode.String, value: "hello" });

// Encode arrays
const arrayResult = encode({
  type: TypeCode.Array,
  value: [
    { type: TypeCode.U8, value: 1 },
    { type: TypeCode.U8, value: 2 },
  ],
});

// Encode maps
const mapResult = encode({
  type: TypeCode.Map,
  value: new Map([
    [{ type: TypeCode.String, value: "key" }, { type: TypeCode.U32, value: 123 }],
  ]),
});
```

### Decoding

```typescript
import { decode } from "@grounds/core";

const result = decode(bytes);
result.match(
  (value) => console.log(value), // DecodedValue
  (error) => console.error(error) // DecodeError
);
```

### Error handling

All operations return `Result<T, E>` from neverthrow:

```typescript
import { encode, TypeCode } from "@grounds/core";

const result = encode({ type: TypeCode.U8, value: 256 }); // Out of range
result.mapErr((error) => {
  console.error(error.code); // "INTEGER_OVERFLOW"
  console.error(error.message); // "u8 value 256 out of range"
});

// Or use match for both success and error cases
result.match(
  (bytes) => console.log("Encoded:", bytes),
  (error) => console.error("Failed:", error.message)
);
```

## API reference

### Types

- `RelishValue` - Tagged union of all Relish value types
- `DecodedValue` - Union type for decoder output (raw JS values)
- `TypeCode` - Enum of type codes (0x00-0x13)
- `EncodeError` - Error type for encoding failures
- `DecodeError` - Error type for decoding failures

### Functions

- `encode(value: RelishValue): Result<Uint8Array, EncodeError>`
- `decode(bytes: Uint8Array): Result<DecodedValue, DecodeError>`

## License

Apache 2.0
npm package: @grounds/schema
Description: TypeBox-based schema definitions for Relish serialization
Author: Bojan Rajkovic
Latest version: 1.0.0

# @grounds/schema

TypeBox-based schema definitions for Relish serialization.

## Installation

```bash
npm install @grounds/schema @sinclair/typebox luxon
npm install -D @types/luxon
```

## Usage

### Defining schemas

```typescript
import {
  RStruct, REnum, RArray, RMap, ROptional,
  RNull, RBool, RU8, RU16, RU32, RU64, RString, RTimestamp,
  field, variant,
} from "@grounds/schema";

// Struct with fields
const UserSchema = RStruct({
  id: field(0, RU64()),
  name: field(1, RString()),
  email: field(2, ROptional(RString())),
  createdAt: field(3, RTimestamp()),
});

// Enum with variants
const MessageSchema = REnum({
  text: variant(0, RStruct({ content: field(0, RString()) })),
  image: variant(1, RStruct({ url: field(0, RString()), width: field(1, RU32()) })),
});

// Collections
const TagsSchema = RArray(RString);
const MetadataSchema = RMap(RString, RString);
```

### Creating codecs

```typescript
import { createCodec } from "@grounds/schema";
import { DateTime } from "luxon";

const userCodec = createCodec(UserSchema);

// Encode
const encoded = userCodec.encode({
  id: 123n,
  name: "Alice",
  email: "alice@example.com",
  createdAt: DateTime.now(),
});

encoded.match(
  (bytes) => console.log("Encoded:", bytes),
  (err) => console.error("Encode failed:", err)
);

// Decode
const decoded = userCodec.decode(bytes);
decoded.match(
  (user) => console.log("Decoded:", user),
  (err) => console.error("Decode failed:", err)
);
```

### Type inference

Schemas provide full TypeScript type inference:

```typescript
import { Static } from "@sinclair/typebox";

type User = Static<typeof UserSchema>;
// { id: bigint; name: string; email: string | null; createdAt: DateTime }

// Enum schemas infer unwrapped union types
type Message = Static<typeof MessageSchema>;
// { content: string } | { url: string; width: number }

// Users handle variant discrimination via type guards on their own discriminator fields
```

## API reference

### Primitive types

- `RNull`, `RBool`
- `RU8`, `RU16`, `RU32`, `RU64`, `RU128`
- `RI8`, `RI16`, `RI32`, `RI64`, `RI128`
- `RF32`, `RF64`
- `RString`, `RTimestamp`

### Composite types

- `RArray(elementType)` - Homogeneous array
- `RMap(keyType, valueType)` - Key-value map
- `ROptional(type)` - Optional value (null when absent)
- `RStruct({ field: field(type, index), ... })` - Struct with indexed fields
- `REnum({ variant: variant(type, index), ... })` - Tagged union

### Codec

- `createCodec(schema)` - Create encoder/decoder for schema

## License

Apache 2.0