@the-situation/core 0.5.0-alpha.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.
- package/dist/distributions/distribution.d.ts +60 -0
- package/dist/distributions/distribution.d.ts.map +1 -0
- package/dist/distributions/distribution.js +10 -0
- package/dist/distributions/distribution.js.map +1 -0
- package/dist/distributions/normal-distribution.d.ts +125 -0
- package/dist/distributions/normal-distribution.d.ts.map +1 -0
- package/dist/distributions/normal-distribution.js +310 -0
- package/dist/distributions/normal-distribution.js.map +1 -0
- package/dist/distributions/normal-sqrt-hints-raw.d.ts +18 -0
- package/dist/distributions/normal-sqrt-hints-raw.d.ts.map +1 -0
- package/dist/distributions/normal-sqrt-hints-raw.js +9 -0
- package/dist/distributions/normal-sqrt-hints-raw.js.map +1 -0
- package/dist/errors/index.d.ts +90 -0
- package/dist/errors/index.d.ts.map +1 -0
- package/dist/errors/index.js +45 -0
- package/dist/errors/index.js.map +1 -0
- package/dist/index.d.ts +14 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +15 -0
- package/dist/index.js.map +1 -0
- package/dist/math/sq128-raw.d.ts +69 -0
- package/dist/math/sq128-raw.d.ts.map +1 -0
- package/dist/math/sq128-raw.js +84 -0
- package/dist/math/sq128-raw.js.map +1 -0
- package/dist/math/sq128.d.ts +191 -0
- package/dist/math/sq128.d.ts.map +1 -0
- package/dist/math/sq128.js +611 -0
- package/dist/math/sq128.js.map +1 -0
- package/package.json +29 -0
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Effect-native error hierarchy for The Situation SDK.
|
|
3
|
+
*
|
|
4
|
+
* All errors extend `Data.TaggedError` so they work seamlessly with Effect's
|
|
5
|
+
* typed error channels.
|
|
6
|
+
*
|
|
7
|
+
* @module
|
|
8
|
+
*/
|
|
9
|
+
import { Data } from 'effect';
|
|
10
|
+
/**
|
|
11
|
+
* Input validation failed (e.g., negative variance, invalid address).
|
|
12
|
+
*/
|
|
13
|
+
export class InvalidInputError extends Data.TaggedError('InvalidInputError') {
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Newton-Raphson or other numerical solver did not converge.
|
|
17
|
+
*/
|
|
18
|
+
export class SolverFailedError extends Data.TaggedError('SolverFailedError') {
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Starknet RPC call failed.
|
|
22
|
+
*/
|
|
23
|
+
export class RpcError extends Data.TaggedError('RpcError') {
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Required data was not found or could not be parsed from an RPC response.
|
|
27
|
+
*/
|
|
28
|
+
export class MissingDataError extends Data.TaggedError('MissingDataError') {
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* Transaction or contract call execution failed.
|
|
32
|
+
*/
|
|
33
|
+
export class ExecutionError extends Data.TaggedError('ExecutionError') {
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* Operation requires a connected account but none is available.
|
|
37
|
+
*/
|
|
38
|
+
export class NotConnectedError extends Data.TaggedError('NotConnectedError') {
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* Requested feature or operation is not supported.
|
|
42
|
+
*/
|
|
43
|
+
export class UnsupportedError extends Data.TaggedError('UnsupportedError') {
|
|
44
|
+
}
|
|
45
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAE9B;;GAEG;AACH,MAAM,OAAO,iBAAkB,SAAQ,IAAI,CAAC,WAAW,CAAC,mBAAmB,CAGzE;CAAG;AAEL;;GAEG;AACH,MAAM,OAAO,iBAAkB,SAAQ,IAAI,CAAC,WAAW,CAAC,mBAAmB,CAGzE;CAAG;AAEL;;GAEG;AACH,MAAM,OAAO,QAAS,SAAQ,IAAI,CAAC,WAAW,CAAC,UAAU,CAGvD;CAAG;AAEL;;GAEG;AACH,MAAM,OAAO,gBAAiB,SAAQ,IAAI,CAAC,WAAW,CAAC,kBAAkB,CAGvE;CAAG;AAEL;;GAEG;AACH,MAAM,OAAO,cAAe,SAAQ,IAAI,CAAC,WAAW,CAAC,gBAAgB,CAInE;CAAG;AAEL;;GAEG;AACH,MAAM,OAAO,iBAAkB,SAAQ,IAAI,CAAC,WAAW,CAAC,mBAAmB,CAEzE;CAAG;AAEL;;GAEG;AACH,MAAM,OAAO,gBAAiB,SAAQ,IAAI,CAAC,WAAW,CAAC,kBAAkB,CAEvE;CAAG"}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @the-situation/core
|
|
3
|
+
*
|
|
4
|
+
* Core types, math primitives, distributions, and Effect error hierarchy.
|
|
5
|
+
*
|
|
6
|
+
* @packageDocumentation
|
|
7
|
+
*/
|
|
8
|
+
export { createSQ128x128Raw, isValidSQ128x128Raw, MAX_LIMB, NEG_ONE_RAW, ONE_RAW, type SQ128x128Raw, ZERO_RAW, } from './math/sq128-raw';
|
|
9
|
+
export { EXP_NEG_TABLE, HALF, INV_SQRT_2PI, MAX, MIN, NEG_ONE, ONE, SQ128x128, TWO, ZERO, } from './math/sq128';
|
|
10
|
+
export type { Distribution } from './distributions/distribution';
|
|
11
|
+
export { NormalDistribution, type NormalDistributionRaw } from './distributions/normal-distribution';
|
|
12
|
+
export type { NormalSqrtHintsRaw } from './distributions/normal-sqrt-hints-raw';
|
|
13
|
+
export { ExecutionError, InvalidInputError, MissingDataError, NotConnectedError, RpcError, type SdkError, SolverFailedError, UnsupportedError, } from './errors';
|
|
14
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,QAAQ,EACR,WAAW,EACX,OAAO,EACP,KAAK,YAAY,EACjB,QAAQ,GACT,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,aAAa,EACb,IAAI,EACJ,YAAY,EACZ,GAAG,EACH,GAAG,EACH,OAAO,EACP,GAAG,EACH,SAAS,EACT,GAAG,EACH,IAAI,GACL,MAAM,cAAc,CAAC;AAGtB,YAAY,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAGjE,OAAO,EAAE,kBAAkB,EAAE,KAAK,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AACrG,YAAY,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAGhF,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,QAAQ,EACR,KAAK,QAAQ,EACb,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,UAAU,CAAC"}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @the-situation/core
|
|
3
|
+
*
|
|
4
|
+
* Core types, math primitives, distributions, and Effect error hierarchy.
|
|
5
|
+
*
|
|
6
|
+
* @packageDocumentation
|
|
7
|
+
*/
|
|
8
|
+
// Math primitives
|
|
9
|
+
export { createSQ128x128Raw, isValidSQ128x128Raw, MAX_LIMB, NEG_ONE_RAW, ONE_RAW, ZERO_RAW, } from './math/sq128-raw';
|
|
10
|
+
export { EXP_NEG_TABLE, HALF, INV_SQRT_2PI, MAX, MIN, NEG_ONE, ONE, SQ128x128, TWO, ZERO, } from './math/sq128';
|
|
11
|
+
// Normal distribution
|
|
12
|
+
export { NormalDistribution } from './distributions/normal-distribution';
|
|
13
|
+
// Effect error hierarchy
|
|
14
|
+
export { ExecutionError, InvalidInputError, MissingDataError, NotConnectedError, RpcError, SolverFailedError, UnsupportedError, } from './errors';
|
|
15
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,kBAAkB;AAClB,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,QAAQ,EACR,WAAW,EACX,OAAO,EAEP,QAAQ,GACT,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,aAAa,EACb,IAAI,EACJ,YAAY,EACZ,GAAG,EACH,GAAG,EACH,OAAO,EACP,GAAG,EACH,SAAS,EACT,GAAG,EACH,IAAI,GACL,MAAM,cAAc,CAAC;AAKtB,sBAAsB;AACtB,OAAO,EAAE,kBAAkB,EAA8B,MAAM,qCAAqC,CAAC;AAGrG,yBAAyB;AACzB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,QAAQ,EAER,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,UAAU,CAAC"}
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Raw representation of SQ128x128 fixed-point numbers.
|
|
3
|
+
*
|
|
4
|
+
* This module provides the low-level data structure that matches the Cairo
|
|
5
|
+
* `SQ128x128Raw` struct used for serialization/deserialization with Starknet.
|
|
6
|
+
*
|
|
7
|
+
* ## Representation
|
|
8
|
+
*
|
|
9
|
+
* A 256-bit signed magnitude number stored as four 64-bit limbs:
|
|
10
|
+
* - magnitude = limb3 * 2^192 + limb2 * 2^128 + limb1 * 2^64 + limb0
|
|
11
|
+
* - sign is stored separately in `neg` flag
|
|
12
|
+
*
|
|
13
|
+
* ## Constraints
|
|
14
|
+
*
|
|
15
|
+
* - All limbs: [0, 2^64 - 1]
|
|
16
|
+
* - neg: true for negative, false for non-negative
|
|
17
|
+
*
|
|
18
|
+
* @module
|
|
19
|
+
*/
|
|
20
|
+
/** Maximum value for all limbs (2^64 - 1) */
|
|
21
|
+
export declare const MAX_LIMB: bigint;
|
|
22
|
+
/**
|
|
23
|
+
* Raw DTO for SQ128x128 serialization to/from Starknet.
|
|
24
|
+
*
|
|
25
|
+
* This is intentionally "dumb data" - no arithmetic operations.
|
|
26
|
+
* Use `SQ128x128` class for computations.
|
|
27
|
+
*/
|
|
28
|
+
export interface SQ128x128Raw {
|
|
29
|
+
/** Lowest 64 bits of magnitude */
|
|
30
|
+
readonly limb0: bigint;
|
|
31
|
+
/** Second 64 bits of magnitude */
|
|
32
|
+
readonly limb1: bigint;
|
|
33
|
+
/** Third 64 bits of magnitude */
|
|
34
|
+
readonly limb2: bigint;
|
|
35
|
+
/** Highest 64 bits of magnitude */
|
|
36
|
+
readonly limb3: bigint;
|
|
37
|
+
/** Sign flag: true = negative, false = non-negative */
|
|
38
|
+
readonly neg: boolean;
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* Validates whether a raw value has valid limb ranges.
|
|
42
|
+
*
|
|
43
|
+
* @param raw - The raw value to validate
|
|
44
|
+
* @returns true if all limbs are within valid ranges
|
|
45
|
+
*/
|
|
46
|
+
export declare function isValidSQ128x128Raw(raw: SQ128x128Raw): boolean;
|
|
47
|
+
/**
|
|
48
|
+
* Creates a validated SQ128x128Raw.
|
|
49
|
+
*
|
|
50
|
+
* @param limb0 - Lowest 64 bits
|
|
51
|
+
* @param limb1 - Second 64 bits
|
|
52
|
+
* @param limb2 - Third 64 bits
|
|
53
|
+
* @param limb3 - Highest 64 bits
|
|
54
|
+
* @param neg - Sign flag
|
|
55
|
+
* @returns The raw value if valid, null otherwise
|
|
56
|
+
*/
|
|
57
|
+
export declare function createSQ128x128Raw(limb0: bigint, limb1: bigint, limb2: bigint, limb3: bigint, neg: boolean): SQ128x128Raw | null;
|
|
58
|
+
/** Zero (0.0) in raw representation */
|
|
59
|
+
export declare const ZERO_RAW: SQ128x128Raw;
|
|
60
|
+
/**
|
|
61
|
+
* One (1.0) in raw representation.
|
|
62
|
+
*
|
|
63
|
+
* 1.0 = 2^128 / 2^128, so the magnitude is exactly 2^128.
|
|
64
|
+
* In limbs: limb3 = 0, limb2 = 1, limb1 = 0, limb0 = 0
|
|
65
|
+
*/
|
|
66
|
+
export declare const ONE_RAW: SQ128x128Raw;
|
|
67
|
+
/** Negative one (-1.0) in raw representation */
|
|
68
|
+
export declare const NEG_ONE_RAW: SQ128x128Raw;
|
|
69
|
+
//# sourceMappingURL=sq128-raw.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"sq128-raw.d.ts","sourceRoot":"","sources":["../../src/math/sq128-raw.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,6CAA6C;AAC7C,eAAO,MAAM,QAAQ,EAAE,MAAyB,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mCAAmC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAW9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,OAAO,GACX,YAAY,GAAG,IAAI,CAGrB;AAMD,uCAAuC;AACvC,eAAO,MAAM,QAAQ,EAAE,YAMtB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,OAAO,EAAE,YAMrB,CAAC;AAEF,gDAAgD;AAChD,eAAO,MAAM,WAAW,EAAE,YAMzB,CAAC"}
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Raw representation of SQ128x128 fixed-point numbers.
|
|
3
|
+
*
|
|
4
|
+
* This module provides the low-level data structure that matches the Cairo
|
|
5
|
+
* `SQ128x128Raw` struct used for serialization/deserialization with Starknet.
|
|
6
|
+
*
|
|
7
|
+
* ## Representation
|
|
8
|
+
*
|
|
9
|
+
* A 256-bit signed magnitude number stored as four 64-bit limbs:
|
|
10
|
+
* - magnitude = limb3 * 2^192 + limb2 * 2^128 + limb1 * 2^64 + limb0
|
|
11
|
+
* - sign is stored separately in `neg` flag
|
|
12
|
+
*
|
|
13
|
+
* ## Constraints
|
|
14
|
+
*
|
|
15
|
+
* - All limbs: [0, 2^64 - 1]
|
|
16
|
+
* - neg: true for negative, false for non-negative
|
|
17
|
+
*
|
|
18
|
+
* @module
|
|
19
|
+
*/
|
|
20
|
+
/** Maximum value for all limbs (2^64 - 1) */
|
|
21
|
+
export const MAX_LIMB = (1n << 64n) - 1n;
|
|
22
|
+
/**
|
|
23
|
+
* Validates whether a raw value has valid limb ranges.
|
|
24
|
+
*
|
|
25
|
+
* @param raw - The raw value to validate
|
|
26
|
+
* @returns true if all limbs are within valid ranges
|
|
27
|
+
*/
|
|
28
|
+
export function isValidSQ128x128Raw(raw) {
|
|
29
|
+
return (raw.limb0 >= 0n &&
|
|
30
|
+
raw.limb0 <= MAX_LIMB &&
|
|
31
|
+
raw.limb1 >= 0n &&
|
|
32
|
+
raw.limb1 <= MAX_LIMB &&
|
|
33
|
+
raw.limb2 >= 0n &&
|
|
34
|
+
raw.limb2 <= MAX_LIMB &&
|
|
35
|
+
raw.limb3 >= 0n &&
|
|
36
|
+
raw.limb3 <= MAX_LIMB);
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Creates a validated SQ128x128Raw.
|
|
40
|
+
*
|
|
41
|
+
* @param limb0 - Lowest 64 bits
|
|
42
|
+
* @param limb1 - Second 64 bits
|
|
43
|
+
* @param limb2 - Third 64 bits
|
|
44
|
+
* @param limb3 - Highest 64 bits
|
|
45
|
+
* @param neg - Sign flag
|
|
46
|
+
* @returns The raw value if valid, null otherwise
|
|
47
|
+
*/
|
|
48
|
+
export function createSQ128x128Raw(limb0, limb1, limb2, limb3, neg) {
|
|
49
|
+
const raw = { limb0, limb1, limb2, limb3, neg };
|
|
50
|
+
return isValidSQ128x128Raw(raw) ? raw : null;
|
|
51
|
+
}
|
|
52
|
+
// ============================================================================
|
|
53
|
+
// Constants
|
|
54
|
+
// ============================================================================
|
|
55
|
+
/** Zero (0.0) in raw representation */
|
|
56
|
+
export const ZERO_RAW = {
|
|
57
|
+
limb0: 0n,
|
|
58
|
+
limb1: 0n,
|
|
59
|
+
limb2: 0n,
|
|
60
|
+
limb3: 0n,
|
|
61
|
+
neg: false,
|
|
62
|
+
};
|
|
63
|
+
/**
|
|
64
|
+
* One (1.0) in raw representation.
|
|
65
|
+
*
|
|
66
|
+
* 1.0 = 2^128 / 2^128, so the magnitude is exactly 2^128.
|
|
67
|
+
* In limbs: limb3 = 0, limb2 = 1, limb1 = 0, limb0 = 0
|
|
68
|
+
*/
|
|
69
|
+
export const ONE_RAW = {
|
|
70
|
+
limb0: 0n,
|
|
71
|
+
limb1: 0n,
|
|
72
|
+
limb2: 1n,
|
|
73
|
+
limb3: 0n,
|
|
74
|
+
neg: false,
|
|
75
|
+
};
|
|
76
|
+
/** Negative one (-1.0) in raw representation */
|
|
77
|
+
export const NEG_ONE_RAW = {
|
|
78
|
+
limb0: 0n,
|
|
79
|
+
limb1: 0n,
|
|
80
|
+
limb2: 1n,
|
|
81
|
+
limb3: 0n,
|
|
82
|
+
neg: true,
|
|
83
|
+
};
|
|
84
|
+
//# sourceMappingURL=sq128-raw.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"sq128-raw.js","sourceRoot":"","sources":["../../src/math/sq128-raw.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,6CAA6C;AAC7C,MAAM,CAAC,MAAM,QAAQ,GAAW,CAAC,EAAE,IAAI,GAAG,CAAC,GAAG,EAAE,CAAC;AAqBjD;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAiB;IACnD,OAAO,CACL,GAAG,CAAC,KAAK,IAAI,EAAE;QACf,GAAG,CAAC,KAAK,IAAI,QAAQ;QACrB,GAAG,CAAC,KAAK,IAAI,EAAE;QACf,GAAG,CAAC,KAAK,IAAI,QAAQ;QACrB,GAAG,CAAC,KAAK,IAAI,EAAE;QACf,GAAG,CAAC,KAAK,IAAI,QAAQ;QACrB,GAAG,CAAC,KAAK,IAAI,EAAE;QACf,GAAG,CAAC,KAAK,IAAI,QAAQ,CACtB,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAa,EACb,KAAa,EACb,KAAa,EACb,KAAa,EACb,GAAY;IAEZ,MAAM,GAAG,GAAiB,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IAC9D,OAAO,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/C,CAAC;AAED,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E,uCAAuC;AACvC,MAAM,CAAC,MAAM,QAAQ,GAAiB;IACpC,KAAK,EAAE,EAAE;IACT,KAAK,EAAE,EAAE;IACT,KAAK,EAAE,EAAE;IACT,KAAK,EAAE,EAAE;IACT,GAAG,EAAE,KAAK;CACX,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAAiB;IACnC,KAAK,EAAE,EAAE;IACT,KAAK,EAAE,EAAE;IACT,KAAK,EAAE,EAAE;IACT,KAAK,EAAE,EAAE;IACT,GAAG,EAAE,KAAK;CACX,CAAC;AAEF,gDAAgD;AAChD,MAAM,CAAC,MAAM,WAAW,GAAiB;IACvC,KAAK,EAAE,EAAE;IACT,KAAK,EAAE,EAAE;IACT,KAAK,EAAE,EAAE;IACT,KAAK,EAAE,EAAE;IACT,GAAG,EAAE,IAAI;CACV,CAAC"}
|
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* SQ128x128 fixed-point number type.
|
|
3
|
+
*
|
|
4
|
+
* An immutable fixed-point number with 128 bits of integer precision
|
|
5
|
+
* and 128 bits of fractional precision.
|
|
6
|
+
*
|
|
7
|
+
* ## Range
|
|
8
|
+
* - Minimum: -2^128 ≈ -3.4×10³⁸
|
|
9
|
+
* - Maximum: 2^128 - 2^-128 ≈ 3.4×10³⁸
|
|
10
|
+
*
|
|
11
|
+
* ## Design
|
|
12
|
+
* - Immutable: all operations return new instances
|
|
13
|
+
* - Safe: operations return null on overflow/underflow
|
|
14
|
+
* - Compatible: toRaw()/fromRaw() for Starknet serialization
|
|
15
|
+
*
|
|
16
|
+
* @module
|
|
17
|
+
*/
|
|
18
|
+
import { type SQ128x128Raw } from './sq128-raw';
|
|
19
|
+
/**
|
|
20
|
+
* An immutable signed Q128.128 fixed-point number.
|
|
21
|
+
*/
|
|
22
|
+
export declare class SQ128x128 {
|
|
23
|
+
private readonly magnitude;
|
|
24
|
+
private readonly negative;
|
|
25
|
+
private constructor();
|
|
26
|
+
/**
|
|
27
|
+
* Creates an SQ128x128 from a JavaScript number.
|
|
28
|
+
*
|
|
29
|
+
* @param value - The number to convert
|
|
30
|
+
* @returns The SQ128x128 value, or null if overflow/invalid
|
|
31
|
+
*/
|
|
32
|
+
static fromNumber(value: number): SQ128x128 | null;
|
|
33
|
+
/**
|
|
34
|
+
* Creates an SQ128x128 from a bigint integer value.
|
|
35
|
+
*
|
|
36
|
+
* @param value - The integer to convert
|
|
37
|
+
* @returns The SQ128x128 value, or null if overflow
|
|
38
|
+
*/
|
|
39
|
+
static fromBigInt(value: bigint): SQ128x128 | null;
|
|
40
|
+
/**
|
|
41
|
+
* Creates an SQ128x128 from a raw representation.
|
|
42
|
+
*
|
|
43
|
+
* @param raw - The raw limb representation
|
|
44
|
+
* @returns The SQ128x128 value, or null if invalid
|
|
45
|
+
*/
|
|
46
|
+
static fromRaw(raw: SQ128x128Raw): SQ128x128 | null;
|
|
47
|
+
/**
|
|
48
|
+
* Converts to a raw representation for Starknet serialization.
|
|
49
|
+
*/
|
|
50
|
+
toRaw(): SQ128x128Raw;
|
|
51
|
+
/**
|
|
52
|
+
* Converts to a JavaScript number.
|
|
53
|
+
*
|
|
54
|
+
* Note: May lose precision for very large or very small values.
|
|
55
|
+
*/
|
|
56
|
+
toNumber(): number;
|
|
57
|
+
/**
|
|
58
|
+
* Returns the underlying scaled magnitude as a bigint.
|
|
59
|
+
*/
|
|
60
|
+
toScaledBigInt(): bigint;
|
|
61
|
+
/**
|
|
62
|
+
* Tests equality with another SQ128x128.
|
|
63
|
+
*/
|
|
64
|
+
eq(other: SQ128x128): boolean;
|
|
65
|
+
/**
|
|
66
|
+
* Tests if this value is less than another.
|
|
67
|
+
*/
|
|
68
|
+
lt(other: SQ128x128): boolean;
|
|
69
|
+
/**
|
|
70
|
+
* Tests if this value is greater than another.
|
|
71
|
+
*/
|
|
72
|
+
gt(other: SQ128x128): boolean;
|
|
73
|
+
/**
|
|
74
|
+
* Tests if this value is less than or equal to another.
|
|
75
|
+
*/
|
|
76
|
+
lte(other: SQ128x128): boolean;
|
|
77
|
+
/**
|
|
78
|
+
* Tests if this value is greater than or equal to another.
|
|
79
|
+
*/
|
|
80
|
+
gte(other: SQ128x128): boolean;
|
|
81
|
+
/**
|
|
82
|
+
* Returns true if this value is zero.
|
|
83
|
+
*/
|
|
84
|
+
isZero(): boolean;
|
|
85
|
+
/**
|
|
86
|
+
* Returns true if this value is negative.
|
|
87
|
+
*/
|
|
88
|
+
isNegative(): boolean;
|
|
89
|
+
/**
|
|
90
|
+
* Returns true if this value is positive (greater than zero).
|
|
91
|
+
*/
|
|
92
|
+
isPositive(): boolean;
|
|
93
|
+
/**
|
|
94
|
+
* Adds another SQ128x128 to this value.
|
|
95
|
+
*
|
|
96
|
+
* @returns The sum, or null on overflow
|
|
97
|
+
*/
|
|
98
|
+
add(other: SQ128x128): SQ128x128 | null;
|
|
99
|
+
/**
|
|
100
|
+
* Subtracts another SQ128x128 from this value.
|
|
101
|
+
*
|
|
102
|
+
* @returns The difference, or null on overflow
|
|
103
|
+
*/
|
|
104
|
+
sub(other: SQ128x128): SQ128x128 | null;
|
|
105
|
+
/**
|
|
106
|
+
* Multiplies by another SQ128x128.
|
|
107
|
+
*
|
|
108
|
+
* @returns The product (rounded toward zero), or null on overflow
|
|
109
|
+
*/
|
|
110
|
+
mul(other: SQ128x128): SQ128x128 | null;
|
|
111
|
+
/**
|
|
112
|
+
* Divides by another SQ128x128.
|
|
113
|
+
*
|
|
114
|
+
* @returns The quotient (rounded toward zero), or null on division by zero/overflow
|
|
115
|
+
*/
|
|
116
|
+
div(other: SQ128x128): SQ128x128 | null;
|
|
117
|
+
/**
|
|
118
|
+
* Returns the negation of this value.
|
|
119
|
+
*
|
|
120
|
+
* @returns The negated value, or null if negating MIN would overflow
|
|
121
|
+
*/
|
|
122
|
+
neg(): SQ128x128 | null;
|
|
123
|
+
/**
|
|
124
|
+
* Returns the absolute value.
|
|
125
|
+
*/
|
|
126
|
+
abs(): SQ128x128;
|
|
127
|
+
/**
|
|
128
|
+
* Computes the square of this value (x * x).
|
|
129
|
+
*
|
|
130
|
+
* More efficient than mul(this) as we can skip sign computation.
|
|
131
|
+
*
|
|
132
|
+
* @returns The squared value, or null on overflow
|
|
133
|
+
*/
|
|
134
|
+
pow2(): SQ128x128 | null;
|
|
135
|
+
/**
|
|
136
|
+
* Computes the floor (integer part) of the absolute value.
|
|
137
|
+
*
|
|
138
|
+
* @returns The integer part as a number
|
|
139
|
+
*/
|
|
140
|
+
floor(): number;
|
|
141
|
+
/**
|
|
142
|
+
* Computes the fractional part (value - floor).
|
|
143
|
+
*
|
|
144
|
+
* @returns The fractional part as SQ128x128
|
|
145
|
+
*/
|
|
146
|
+
frac(): SQ128x128;
|
|
147
|
+
/**
|
|
148
|
+
* Computes exp(-|self|) for this value.
|
|
149
|
+
*
|
|
150
|
+
* Uses range reduction: exp(-u) = exp(-k) * exp(-(u mod 1))
|
|
151
|
+
* where k = floor(u) and the fractional part uses Taylor series.
|
|
152
|
+
*
|
|
153
|
+
* @returns The exponential value, or null if computation fails
|
|
154
|
+
*/
|
|
155
|
+
expNeg(): SQ128x128 | null;
|
|
156
|
+
/**
|
|
157
|
+
* Computes exp(-x²/2) for this value.
|
|
158
|
+
*
|
|
159
|
+
* This is a common operation in normal distribution computations.
|
|
160
|
+
*
|
|
161
|
+
* @returns The exponential value, or null if computation fails
|
|
162
|
+
*/
|
|
163
|
+
expNegHalfSquared(): SQ128x128 | null;
|
|
164
|
+
}
|
|
165
|
+
/** Zero (0.0) */
|
|
166
|
+
export declare const ZERO: SQ128x128;
|
|
167
|
+
/** Half (0.5) */
|
|
168
|
+
export declare const HALF: SQ128x128;
|
|
169
|
+
/** Two (2.0) */
|
|
170
|
+
export declare const TWO: SQ128x128;
|
|
171
|
+
/** One (1.0) */
|
|
172
|
+
export declare const ONE: SQ128x128;
|
|
173
|
+
/** Negative one (-1.0) */
|
|
174
|
+
export declare const NEG_ONE: SQ128x128;
|
|
175
|
+
/** Minimum value - practical limit for testing (using bigint for precision) */
|
|
176
|
+
export declare const MIN: SQ128x128;
|
|
177
|
+
/** Maximum value - practical limit for testing (using bigint for precision) */
|
|
178
|
+
export declare const MAX: SQ128x128;
|
|
179
|
+
/**
|
|
180
|
+
* 1/√(2π) ≈ 0.3989422804014327
|
|
181
|
+
*
|
|
182
|
+
* This constant is used in normal distribution PDF computation.
|
|
183
|
+
*/
|
|
184
|
+
export declare const INV_SQRT_2PI: SQ128x128;
|
|
185
|
+
/**
|
|
186
|
+
* Precomputed exp(-k) lookup table for k = 0..10.
|
|
187
|
+
*
|
|
188
|
+
* For k > 10, exp(-k) < 2e-5, effectively zero for our precision.
|
|
189
|
+
*/
|
|
190
|
+
export declare const EXP_NEG_TABLE: SQ128x128[];
|
|
191
|
+
//# sourceMappingURL=sq128.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"sq128.d.ts","sourceRoot":"","sources":["../../src/math/sq128.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAKL,KAAK,YAAY,EAElB,MAAM,aAAa,CAAC;AA8BrB;;GAEG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IAEnC,OAAO;IAKP;;;;;OAKG;WACW,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAiCzD;;;;;OAKG;WACW,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAYzD;;;;;OAKG;WACW,OAAO,CAAC,GAAG,EAAE,YAAY,GAAG,SAAS,GAAG,IAAI;IAS1D;;OAEG;IACI,KAAK,IAAI,YAAY;IAK5B;;;;OAIG;IACI,QAAQ,IAAI,MAAM;IAKzB;;OAEG;IACI,cAAc,IAAI,MAAM;IAQ/B;;OAEG;IACI,EAAE,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO;IAIpC;;OAEG;IACI,EAAE,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO;IAUpC;;OAEG;IACI,EAAE,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO;IAIpC;;OAEG;IACI,GAAG,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO;IAIrC;;OAEG;IACI,GAAG,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO;IAQrC;;OAEG;IACI,MAAM,IAAI,OAAO;IAIxB;;OAEG;IACI,UAAU,IAAI,OAAO;IAI5B;;OAEG;IACI,UAAU,IAAI,OAAO;IAQ5B;;;;OAIG;IACI,GAAG,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,IAAI;IAe9C;;;;OAIG;IACI,GAAG,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,IAAI;IAe9C;;;;OAIG;IACI,GAAG,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,IAAI;IAa9C;;;;OAIG;IACI,GAAG,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,IAAI;IAgB9C;;;;OAIG;IACI,GAAG,IAAI,SAAS,GAAG,IAAI;IAO9B;;OAEG;IACI,GAAG,IAAI,SAAS;IAIvB;;;;;;OAMG;IACI,IAAI,IAAI,SAAS,GAAG,IAAI;IAY/B;;;;OAIG;IACI,KAAK,IAAI,MAAM;IAMtB;;;;OAIG;IACI,IAAI,IAAI,SAAS;IAOxB;;;;;;;OAOG;IACI,MAAM,IAAI,SAAS,GAAG,IAAI;IAkCjC;;;;;;OAMG;IACI,iBAAiB,IAAI,SAAS,GAAG,IAAI;CAc7C;AAMD,iBAAiB;AACjB,eAAO,MAAM,IAAI,EAAE,SAAoD,CAAC;AAExE,iBAAiB;AACjB,eAAO,MAAM,IAAI,EAAE,SAMJ,CAAC;AAEhB,gBAAgB;AAChB,eAAO,MAAM,GAAG,EAAE,SAMH,CAAC;AAEhB,gBAAgB;AAChB,eAAO,MAAM,GAAG,EAAE,SAAmD,CAAC;AAEtE,0BAA0B;AAC1B,eAAO,MAAM,OAAO,EAAE,SAAuD,CAAC;AAE9E,+EAA+E;AAC/E,eAAO,MAAM,GAAG,EAAE,SAA2D,CAAC;AAE9E,+EAA+E;AAC/E,eAAO,MAAM,GAAG,EAAE,SAA+D,CAAC;AAMlF;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,SAMZ,CAAC;AAEhB;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,EAmFpC,CAAC"}
|