0
# Utilities and Helpers
1

2
Utility functions for mode detection, URL validation, and configuration merging to support the core embedding functionality. These helpers provide common functionality used throughout the vega-embed library.
3

4
## Capabilities
5

6
### Mode Detection
7

8
Automatically determine whether a specification is Vega or Vega-Lite format.
9

10
```typescript { .api }
11
/**
12
 * Guess the mode (vega or vega-lite) of a specification
13
 * @param spec - The visualization specification to analyze
14
 * @param providedMode - Optional mode override
15
 * @returns The detected or provided mode
16
 */
17
function guessMode(spec: VisualizationSpec, providedMode?: Mode): Mode;
18

19
type Mode = 'vega' | 'vega-lite';
20
```
21

22
**Usage Examples:**
23

24
```typescript
25
import { guessMode } from "vega-embed";
26

27
// Detect mode from spec
28
const vlSpec = {
29
  mark: "bar",
30
  data: { values: [{ a: "A", b: 28 }] },
31
  encoding: { x: { field: "a" }, y: { field: "b" } }
32
};
33

34
const mode = guessMode(vlSpec); // Returns 'vega-lite'
35

36
// With $schema, mode is detected from schema URL
37
const specWithSchema = {
38
  $schema: "https://vega.github.io/schema/vega-lite/v5.json",
39
  mark: "point",
40
  // ...
41
};
42

43
const detectedMode = guessMode(specWithSchema); // Returns 'vega-lite'
44

45
// Override mode detection
46
const forcedMode = guessMode(vlSpec, 'vega'); // Returns 'vega' (with warning)
47
```
48

49
### Mode Detection Logic
50

51
The function uses several strategies to determine the specification format:
52

53
1. **Schema Analysis**: If `$schema` is present, parses the URL to determine format
54
2. **Vega-Lite Indicators**: Looks for `mark`, `encoding`, `layer`, `hconcat`, `vconcat`, `repeat`, `facet` properties
55
3. **Fallback**: Defaults to 'vega' if no clear indicators are found
56

57
### URL Validation
58

59
Check if a string represents a valid URL for loading specifications.
60

61
```typescript { .api }
62
/**
63
 * Check if a string is a URL
64
 * @param s - String to test
65
 * @returns True if the string appears to be a URL
66
 */
67
function isURL(s: string): boolean;
68
```
69

70
**Usage Examples:**
71

72
```typescript
73
import { isURL } from "vega-embed";
74

75
// Valid URLs
76
console.log(isURL("https://example.com/spec.json")); // true
77
console.log(isURL("http://localhost:3000/data.json")); // true
78
console.log(isURL("//cdn.example.com/chart.vg.json")); // true
79

80
// Not URLs
81
console.log(isURL("spec.json")); // false
82
console.log(isURL("{ mark: 'bar' }")); // false
83
console.log(isURL("/local/path.json")); // false
84
```
85

86
### Deep Configuration Merging
87

88
Merge configuration objects recursively for options composition.
89

90
```typescript { .api }
91
/**
92
 * Deep merge configuration objects
93
 * @param dest - Destination object to merge into
94
 * @param src - Source objects to merge from
95
 * @returns The merged destination object
96
 */
97
function mergeDeep<T>(dest: T, ...src: readonly DeepPartial<T>[]): T;
98

99
type DeepPartial<T> = {
100
  [P in keyof T]?: P extends unknown ? unknown : DeepPartial<T[P]>;
101
};
102
```
103

104
**Usage Examples:**
105

106
```typescript
107
import { mergeDeep } from "vega-embed";
108

109
const baseConfig = {
110
  actions: { export: true, source: false },
111
  renderer: "canvas",
112
  theme: "default"
113
};
114

115
const userConfig = {
116
  actions: { source: true },
117
  width: 400
118
};
119

120
const merged = mergeDeep(baseConfig, userConfig);
121
// Result: {
122
//   actions: { export: true, source: true },
123
//   renderer: "canvas",
124
//   theme: "default",
125
//   width: 400
126
// }
127
```
128

129
### Type Definitions
130

131
Core type definitions used throughout the utility functions.
132

133
```typescript { .api }
134
type Mode = 'vega' | 'vega-lite';
135

136
type Config = VlConfig | VgConfig;
137

138
type ExpressionFunction = Record<string, any | { fn: any; visitor?: any }>;
139

140
type DeepPartial<T> = {
141
  [P in keyof T]?: P extends unknown ? unknown : DeepPartial<T[P]>;
142
};
143
```
144

145
### Message Data Structure
146

147
Data structure for communication with external editors and tools.
148

149
```typescript { .api }
150
interface MessageData {
151
  /** Specification as JSON string */
152
  spec: string;
153
  
154
  /** Optional file data */
155
  file?: unknown;
156
  
157
  /** Configuration object */
158
  config?: Config;
159
  
160
  /** Visualization mode */
161
  mode: Mode;
162
  
163
  /** Rendering backend */
164
  renderer?: Renderers;
165
}
166
```
167

168
This interface is used when communicating with the Vega Editor or other external tools through the post message system.
169

170
### Version Information
171

172
Access to package version information.
173

174
```typescript { .api }
175
/** Current version of vega-embed package */
176
const version: string;
177
```
178

179
**Usage Examples:**
180

181
```typescript
182
import { version } from "vega-embed";
183

184
console.log(`Using vega-embed version ${version}`);
185
```
186

187
### Re-exported Libraries
188

189
Access to the underlying Vega and Vega-Lite libraries.
190

191
```typescript { .api }
192
/** Vega library re-export */
193
const vega: typeof vegaImport;
194

195
/** Vega-Lite library re-export with backwards compatibility */
196
let vegaLite: typeof vegaLiteImport;
197
```
198

199
**Usage Examples:**
200

201
```typescript
202
import { vega, vegaLite } from "vega-embed";
203

204
// Access Vega functions directly
205
const view = new vega.View(vega.parse(spec));
206

207
// Access Vega-Lite compilation
208
const compiled = vegaLite.compile(vlSpec);
209
```
210

211
The `vegaLite` export includes backwards compatibility logic for older versions of Vega-Lite and browser environments.