1/**
2 * The `PrimaryKey` module defines a small protocol for values that can expose
3 * a stable, string-based identifier. A value participates by implementing a
4 * method at {@link symbol}; consumers can check unknown values with
5 * {@link isPrimaryKey} and read the key with {@link value}.
6 *
7 * @since 2.0.0
8 */
9
10import { hasProperty } from "./Predicate.ts"
11
12/**
13 * Defines the unique identifier used to identify objects that implement the `PrimaryKey` interface.
14 *
15 * **When to use**
16 *
17 * Use to implement the `PrimaryKey` protocol as a computed property key on
18 * classes or object literals that expose a stable string identifier.
19 *
20 * @see {@link PrimaryKey} for the protocol interface that declares the method keyed by this symbol
21 * @see {@link value} for reading the string key from a `PrimaryKey` value
22 * @see {@link isPrimaryKey} for checking whether an unknown value carries this method
23 *
24 * @category symbols
25 * @since 2.0.0
26 */
27export const symbol = "~effect/PrimaryKey"
28
29/**
30 * An interface for objects that can provide a string-based primary key.
31 *
32 * **When to use**
33 *
34 * Use to define values that expose a stable string identifier for equality,
35 * hashing, caching, or persistence.
36 *
37 * **Details**
38 *
39 * Objects implementing this interface must provide a method that returns
40 * a unique string identifier.
41 *
42 * **Example** (Implementing a primary key)
43 *
44 * ```ts import.meta.vitest
45 * import { PrimaryKey } from "effect"
46 *
47 * class ProductId implements PrimaryKey.PrimaryKey {
48 * constructor(private category: string, private id: number) {}
49 *
50 * [PrimaryKey.symbol](): string {
51 * return `${this.category}-${this.id}`
52 * }
53 * }
54 *
55 * const productId = new ProductId("electronics", 42)
56 * PrimaryKey.value(productId) // => "electronics-42"
57 * ```
58 *
59 * @category models
60 * @since 2.0.0
61 */
62export interface PrimaryKey {
63 [symbol](): string
64}
65
66/**
67 * Checks whether a value implements the `PrimaryKey` protocol.
68 *
69 * **When to use**
70 *
71 * Use to narrow an unknown value before treating it as a `PrimaryKey`.
72 *
73 * **Details**
74 *
75 * This is a structural guard for the `PrimaryKey.symbol` property.
76 *
77 * **Gotchas**
78 *
79 * This guard does not call the method or verify that it returns a string.
80 *
81 * @see {@link PrimaryKey} for the protocol being checked
82 * @see {@link value} for extracting the string value after narrowing
83 *
84 * @category guards
85 * @since 4.0.0
86 */
87export const isPrimaryKey = (u: unknown): u is PrimaryKey => hasProperty(u, symbol)
88
89/**
90 * Extracts the string value from a `PrimaryKey`.
91 *
92 * **When to use**
93 *
94 * Use to read the stable string identifier from a value that implements
95 * `PrimaryKey`.
96 *
97 * **Example** (Reading primary key values)
98 *
99 * ```ts import.meta.vitest
100 * import { PrimaryKey } from "effect"
101 *
102 * class OrderId implements PrimaryKey.PrimaryKey {
103 * constructor(private timestamp: number, private sequence: number) {}
104 *
105 * [PrimaryKey.symbol](): string {
106 * return `order_${this.timestamp}_${this.sequence}`
107 * }
108 * }
109 *
110 * const orderId = new OrderId(1640995200000, 1)
111 * PrimaryKey.value(orderId) // => "order_1640995200000_1"
112 *
113 * // Can also be used with simple string-based implementations
114 * const simpleKey = {
115 * [PrimaryKey.symbol]: () => "simple-key-123"
116 * }
117 * PrimaryKey.value(simpleKey) // => "simple-key-123"
118 * ```
119 *
120 * @category getters
121 * @since 2.0.0
122 */
123export const value = (self: PrimaryKey): string => self[symbol]()