@peridotvault/peridotbase-sdk 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,229 @@
1
+ /** Logical column types supported by the PoC program. */
2
+ export type ColumnTypeName = "bool" | "i64" | "decimal" | "text" | "uuid" | "date" | "timestamp" | "interval" | "address" | "inet" | "cidr" | "macaddr" | "bit" | "varbit" | "range" | "numrange" | "tsrange" | "daterange" | "time";
3
+ /** Fixed-point decimal value: `decimal` scaled by 10^-`scale`. */
4
+ export type DecimalValue = {
5
+ decimal: bigint;
6
+ scale: number;
7
+ };
8
+ /**
9
+ * User-facing SQL value. `i64` values are represented as `number | bigint |
10
+ * string`; UUID values are represented as `Uint8Array` (or a canonical UUID
11
+ * string that has been coerced first).
12
+ */
13
+ /** Reference to a TEXT value stored out-of-line in overflow chunk accounts. */
14
+ export interface OverflowReference {
15
+ /** Deterministic 32-byte digest of `(table, primary key, column, nonce)`. */
16
+ key: Uint8Array;
17
+ chunks: number;
18
+ len: number;
19
+ }
20
+ /** On-chain `Value::Ref` payload. Resolved to its TEXT value when read. */
21
+ export type OverflowValue = {
22
+ ref: OverflowReference;
23
+ };
24
+ export type AddressValue = {
25
+ address: Uint8Array;
26
+ };
27
+ export type InetValue = {
28
+ inet: Uint8Array;
29
+ prefix: number;
30
+ };
31
+ export type MacValue = {
32
+ mac: Uint8Array;
33
+ };
34
+ export type BitValue = {
35
+ bit: Uint8Array;
36
+ length: number;
37
+ };
38
+ export type RangeValue = {
39
+ range: {
40
+ start: bigint;
41
+ end: bigint;
42
+ flags: number;
43
+ };
44
+ };
45
+ /**
46
+ * Calendar interval, PostgreSQL's model: months and days are kept apart
47
+ * because their length depends on the calendar; the time part is exact
48
+ * microseconds.
49
+ */
50
+ export type IntervalValue = {
51
+ interval: {
52
+ months: number;
53
+ days: number;
54
+ micros: bigint;
55
+ };
56
+ };
57
+ export type SqlValue = null | undefined | boolean | number | bigint | string | Uint8Array | DecimalValue | AddressValue | InetValue | MacValue | BitValue | IntervalValue | RangeValue | OverflowValue;
58
+ /** Maximum byte length of an inline TEXT value (mirrors `MAX_INLINE_TEXT_LEN`). */
59
+ export declare const MAX_INLINE_TEXT_LEN = 512;
60
+ /** Maximum byte length of a logical TEXT value (mirrors `MAX_TEXT_LEN`). */
61
+ export declare const MAX_TEXT_LEN: number;
62
+ export declare function isOverflowValue(value: SqlValue): value is OverflowValue;
63
+ export interface ColumnSpec {
64
+ name: string;
65
+ type: ColumnTypeName;
66
+ nullable?: boolean;
67
+ scale?: number;
68
+ maxLen?: number;
69
+ default?: SqlValue;
70
+ /** ENUM/DOMAIN catalog name; resolved by `createTable`. */
71
+ typeName?: string;
72
+ /** Resolved catalog PDA (advanced/batched callers). */
73
+ typeRef?: any;
74
+ }
75
+ export declare const COLUMN_TYPE_TO_ANCHOR: Record<ColumnTypeName, any>;
76
+ export declare const ANCHOR_TO_COLUMN_TYPE: Record<string, ColumnTypeName>;
77
+ export declare const CONSTRAINT_KIND_TO_ANCHOR: Record<string, any>;
78
+ /** Guard bits as enforced on-chain by `set_table_guard`. */
79
+ export declare const TABLE_GUARD: {
80
+ readonly appendOnly: 1;
81
+ readonly denyDelete: 2;
82
+ readonly denyUpdate: 4;
83
+ readonly immutable: 8;
84
+ readonly freezePolicies: 16;
85
+ };
86
+ export type TableGuardKind = keyof typeof TABLE_GUARD;
87
+ /** Encodes a guard object into the on-chain bitmask. */
88
+ export declare function encodeGuardBits(guards: Partial<Record<TableGuardKind, boolean>> | undefined): number;
89
+ /** Decodes guard bits into a readable object. */
90
+ export declare function decodeGuardBits(bits: number): Record<TableGuardKind, boolean>;
91
+ export declare const ROLE_TO_ANCHOR: Record<string, any>;
92
+ export declare function toBigInt(value: number | bigint | string): bigint;
93
+ /** Parses a canonical UUID string into its 16-byte representation. */
94
+ export declare function uuidToBytes(value: string): Uint8Array;
95
+ /** Formats 16 raw bytes as a canonical UUID string. */
96
+ export declare function bytesToUuid(bytes: Uint8Array): string;
97
+ /**
98
+ * Parses a `YYYY-MM-DD` literal into days since 1970-01-01 UTC.
99
+ * Round-trips through UTC so an invalid calendar date is rejected rather than
100
+ * silently normalized.
101
+ */
102
+ export declare function dateTextToDays(value: string): bigint;
103
+ /** Formats days since epoch as `YYYY-MM-DD`. */
104
+ export declare function daysToDateText(days: bigint): string;
105
+ /** Parses an ISO-8601 timestamp (or date) into whole UTC seconds. */
106
+ export declare function timestampTextToSeconds(value: string): bigint;
107
+ /** Formats whole UTC seconds as an ISO-8601 timestamp. */
108
+ export declare function secondsToTimestampText(seconds: bigint): string;
109
+ export declare function coerceValue(value: SqlValue, column: {
110
+ type: ColumnTypeName;
111
+ scale?: number;
112
+ }): SqlValue;
113
+ export declare function readI128LE(buffer: Buffer, offset: number): bigint;
114
+ /**
115
+ * Canonical Borsh encoding of a typed `Value`. This must byte-for-byte match
116
+ * the Rust `Value` enum because it is used for PK hashing and index keys.
117
+ */
118
+ export declare function encodeTypedValue(value: SqlValue): Buffer;
119
+ /** Borsh size of a canonical `Value`, in bytes. */
120
+ export declare function typedValueSize(value: SqlValue): number;
121
+ /** Domain separators for v3 digests (frozen PRD §3.2, §5). */ export declare const PK_V3_DOMAIN: Buffer<ArrayBuffer>;
122
+ export declare const UNIQUE_V3_DOMAIN: Buffer<ArrayBuffer>;
123
+ export declare const INDEX_ID_V3_DOMAIN: Buffer<ArrayBuffer>;
124
+ export declare const POSTING_V3_DOMAIN: Buffer<ArrayBuffer>;
125
+ /**
126
+ * Composite index key: `0xFE | count | [u16 len | canonical part]...`.
127
+ * Mirrors Rust `v3_index_key_for_row`.
128
+ */
129
+ export declare function compositeIndexKeyV3(parts: Uint8Array[]): Buffer;
130
+ /**
131
+ * Canonical v3 PK/index key with pinned tags (not enum order).
132
+ * NULL and Ref are rejected as PK keys. Mirrors Rust `canonical_typed_key_v3`.
133
+ */
134
+ export declare function canonicalTypedKeyV3(value: SqlValue): Buffer;
135
+ /**
136
+ * Canonical v3 primary-key bytes for one or more columns. A single column keeps
137
+ * the legacy encoding; composite keys are tagged `0xFE` and length-prefixed.
138
+ */
139
+ export declare function primaryKeyCanonicalV3(values: SqlValue[], columns: number[]): Buffer;
140
+ /**
141
+ * Reverse of `canonicalTypedKeyV3` for covering-index payloads. The tag byte
142
+ * decides the type, so no column spec is needed; NULL is not encoded.
143
+ */
144
+ export declare function decodeCanonicalTypedKeyV3(bytes: Buffer | Uint8Array): SqlValue;
145
+ /**
146
+ * Decodes an INCLUDE payload written by the program: per column
147
+ * `present: u8` then `len: u16 LE` + canonical key when present.
148
+ */
149
+ export declare function decodeCoveringPayload(payload: Buffer | Uint8Array, columnCount: number): (SqlValue | null)[];
150
+ /** D = SHA256("peridotbase:pk:v3" || K). */
151
+ export declare function pkDigestV3(key: Buffer | Uint8Array): Buffer;
152
+ /** U = SHA256("peridotbase:unique:v3" || canonicalIndexedKey). */
153
+ export declare function uniqueDigestV3(key: Buffer | Uint8Array): Buffer;
154
+ /** V = SHA256("peridotbase:posting:v3" || canonicalIndexedKey). */
155
+ export declare function postingDigestV3(key: Buffer | Uint8Array): Buffer;
156
+ /** Converts a canonical value into the Anchor enum object for instruction args. */
157
+ /**
158
+ * The Rust `Value` enum uses tuple variants (`Text(String)`), which the
159
+ * Anchor coder models as a single numerically-named field. Encoding therefore
160
+ * requires the variant payload to be a one-element array; passing the scalar
161
+ * directly is silently truncated to its first character.
162
+ */
163
+ export declare function toAnchorValue(value: SqlValue): any;
164
+ /** Converts an Anchor enum object back into a canonical value. */
165
+ export declare function fromAnchorValue(value: any): SqlValue;
166
+ /** Range flag bits: 0-1 endpoint inclusivity, 2-5 decimal scale. */
167
+ export declare const RANGE_LOWER_INC = 1;
168
+ export declare const RANGE_UPPER_INC = 2;
169
+ export declare const RANGE_SCALE_SHIFT = 2;
170
+ export declare const RANGE_SCALE_MASK = 63;
171
+ /** Decimal scale carried in the range flags (0 for non-numeric ranges). */
172
+ export declare function rangeScale(flags: number): number;
173
+ /** Human-readable projection of a canonical value (UUIDs become strings). */
174
+ export declare function displayValue(value: SqlValue, column?: {
175
+ type: ColumnTypeName;
176
+ }): string | number | boolean | DecimalValue | OverflowValue | AddressValue | InetValue | MacValue | BitValue | RangeValue | IntervalValue | Uint8Array<ArrayBufferLike>;
177
+ /**
178
+ * Locale-aware MONEY formatting without floating-point loss. Granularity comes
179
+ * from the column's decimal scale; the currency is presentation metadata.
180
+ */
181
+ export declare function formatMoney(value: SqlValue, options?: {
182
+ currency?: string;
183
+ locale?: string;
184
+ }): string | null;
185
+ export declare const MICROS_PER_SECOND = 1000000n;
186
+ export declare const MICROS_PER_MINUTE: bigint;
187
+ export declare const MICROS_PER_HOUR: bigint;
188
+ export declare const SECONDS_PER_DAY = 86400n;
189
+ export declare const MICROS_PER_DAY: bigint;
190
+ /** PostgreSQL compares/normalises intervals with a 30-day month. */
191
+ export declare function intervalTotalMicros(interval: {
192
+ months: number;
193
+ days: number;
194
+ micros: bigint;
195
+ }): bigint;
196
+ /**
197
+ * Parses PostgreSQL interval text: `1 year 2 mons 3 days 04:05:06.789`, the
198
+ * `Y-M-D` date form, and plain unit lists. A bare number is seconds, matching
199
+ * `interval '5'`.
200
+ */
201
+ export declare function parseInterval(text: string): IntervalValue;
202
+ /** Canonical PostgreSQL-style text for an interval. */
203
+ export declare function formatInterval(interval: {
204
+ months: number;
205
+ days: number;
206
+ micros: bigint;
207
+ }): string;
208
+ /** Days since 1970-01-01 to a civil date (Howard Hinnant). */
209
+ export declare function civilFromDays(days: bigint): {
210
+ year: number;
211
+ month: number;
212
+ day: number;
213
+ };
214
+ /** Civil date to days since 1970-01-01 (Howard Hinnant). */
215
+ export declare function daysFromCivil(year: number, month: number, day: number): bigint;
216
+ /** Adds calendar months to a day count, clamping the day to the target month. */
217
+ export declare function addMonthsToDays(days: bigint, months: number): bigint;
218
+ /** `DATE + INTERVAL`; rejects a sub-day part because DATE is whole days. */
219
+ export declare function dateAddInterval(days: bigint, interval: {
220
+ months: number;
221
+ days: number;
222
+ micros: bigint;
223
+ }): bigint;
224
+ /** `TIMESTAMP + INTERVAL`; the time of day is preserved and month-ends clamp. */
225
+ export declare function timestampAddInterval(seconds: bigint, interval: {
226
+ months: number;
227
+ days: number;
228
+ micros: bigint;
229
+ }): bigint;