@datafn/server 0.0.2 → 0.0.3

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/index.d.cts CHANGED
@@ -1,149 +1,6 @@
1
+ import { DatafnSchema, DatafnPlugin } from '@datafn/core/types';
1
2
  import { Router } from '@superfunctions/http';
2
- import { Adapter, RedisAdapter, KVStoreAdapter, RowLevelNamespaceConfig } from '@superfunctions/db';
3
-
4
- /**
5
- * Pluggable logger interface and default implementation.
6
- * LOG-001 / Decision #14
7
- */
8
- interface DatafnLogger {
9
- info(message: string, context?: Record<string, unknown>): void;
10
- warn(message: string, context?: Record<string, unknown>): void;
11
- error(message: string, context?: Record<string, unknown>): void;
12
- debug(message: string, context?: Record<string, unknown>): void;
13
- }
14
-
15
- /**
16
- * Execution Timing Middleware (OBS-001 through OBS-004)
17
- * Provides structured phase-level timing for query, mutation, and sync operations.
18
- */
19
- /**
20
- * Timing event emitted after each operation completes.
21
- * Contains phase-by-phase duration breakdown.
22
- * MUST NOT include record data, filter values, or credentials.
23
- */
24
- interface ExecutionTimingEvent {
25
- endpoint: string;
26
- resource?: string;
27
- operation?: string;
28
- phases: Record<string, number>;
29
- totalMs: number;
30
- timestamp: string;
31
- }
32
-
33
- type DatafnPermissionsPolicy = {
34
- read?: {
35
- fields: string[];
36
- };
37
- write?: {
38
- fields: string[];
39
- };
40
- ownerField?: string;
41
- };
42
- type DatafnFieldSchema = {
43
- name: string;
44
- type: "string" | "number" | "boolean" | "object" | "array" | "date" | "file" | "json";
45
- required?: boolean;
46
- nullable?: boolean;
47
- readonly?: boolean;
48
- default?: unknown;
49
- enum?: unknown[];
50
- min?: number;
51
- max?: number;
52
- minLength?: number;
53
- maxLength?: number;
54
- pattern?: string;
55
- unique?: boolean | string;
56
- encrypt?: boolean;
57
- volatile?: boolean;
58
- };
59
- type DatafnResourceSchema = {
60
- name: string;
61
- version: number;
62
- idPrefix?: string;
63
- isRemoteOnly?: boolean;
64
- fields: DatafnFieldSchema[];
65
- indices?: {
66
- base?: string[];
67
- search?: string[];
68
- vector?: string[];
69
- } | string[];
70
- permissions?: DatafnPermissionsPolicy;
71
- capabilities?: unknown;
72
- };
73
- type DatafnRelationSchema = {
74
- from: string | string[];
75
- to: string | string[];
76
- type: "one-many" | "many-one" | "many-many" | "htree";
77
- relation?: string;
78
- inverse?: string;
79
- cache?: boolean;
80
- metadata?: Array<{
81
- name: string;
82
- type: "string" | "number" | "boolean" | "date" | "object" | "json";
83
- }>;
84
- fkField?: string;
85
- pathField?: string;
86
- joinTable?: string;
87
- joinColumns?: {
88
- from: string;
89
- to: string;
90
- };
91
- /** Relation-level capabilities (e.g. "timestamps", "audit") for many-many join rows. */
92
- capabilities?: string[];
93
- };
94
- type DatafnSchema = {
95
- version?: number;
96
- capabilities?: unknown;
97
- resources: DatafnResourceSchema[];
98
- relations?: DatafnRelationSchema[];
99
- namespaced?: boolean;
100
- };
101
- type DatafnHookContext = {
102
- env: "client" | "server";
103
- schema: DatafnSchema;
104
- context?: unknown;
105
- };
106
- type DatafnPlugin = {
107
- name: string;
108
- runsOn: Array<"client" | "server">;
109
- beforeQuery?: (ctx: DatafnHookContext, q: unknown) => Promise<unknown> | unknown;
110
- afterQuery?: (ctx: DatafnHookContext, q: unknown, result: unknown) => Promise<unknown> | unknown;
111
- beforeMutation?: (ctx: DatafnHookContext, m: unknown | unknown[]) => Promise<unknown> | unknown;
112
- afterMutation?: (ctx: DatafnHookContext, m: unknown | unknown[], result: unknown) => Promise<void> | void;
113
- beforeSync?: (ctx: DatafnHookContext, phase: "seed" | "clone" | "pull" | "push" | "cloneUp" | "reconcile", payload: unknown) => Promise<unknown> | unknown;
114
- afterSync?: (ctx: DatafnHookContext, phase: "seed" | "clone" | "pull" | "push" | "cloneUp" | "reconcile", payload: unknown, result: unknown) => Promise<void> | void;
115
- };
116
- interface RetentionConfig {
117
- /** Number of days to retain change log entries. Default: unlimited. */
118
- changeLogDays?: number;
119
- /** Number of days to retain idempotency records. Default: unlimited. */
120
- idempotencyDays?: number;
121
- /** Whether to run pruning on server startup. Default: false. */
122
- pruneOnStartup?: boolean;
123
- /** Interval in milliseconds for periodic pruning. Minimum: 60000. Default: disabled. */
124
- pruneIntervalMs?: number;
125
- }
126
- interface RateLimitConfig<TContext = any> {
127
- /** Enable rate limiting. Default: false. */
128
- enabled: boolean;
129
- /** Max requests per window per client. Default: 100. */
130
- maxRequests?: number;
131
- /** Window duration in seconds. Default: 60. */
132
- windowSeconds?: number;
133
- /** Per-endpoint overrides */
134
- endpoints?: Partial<Record<'query' | 'mutation' | 'transact' | 'push' | 'pull' | 'clone' | 'reconcile' | 'seed', {
135
- maxRequests: number;
136
- windowSeconds: number;
137
- }>>;
138
- /** Key extractor for identifying clients. Default: uses authContext userId or "anonymous". */
139
- keyExtractor?: (ctx: TContext) => string | Promise<string>;
140
- }
141
- interface ObservabilityConfig {
142
- /** Emit execution timing events. Default: false. */
143
- timing?: boolean;
144
- /** Custom timing event handler. Default: console.debug. */
145
- onTiming?: (event: ExecutionTimingEvent) => void;
146
- }
3
+ import { Adapter, KVStoreAdapter, RedisAdapter, RowLevelNamespaceConfig } from '@superfunctions/db';
147
4
 
148
5
  /**
149
6
  * SearchProvider interface for server-side search integration.
@@ -192,6 +49,17 @@ interface SearchProvider {
192
49
  dispose?(): Promise<void>;
193
50
  }
194
51
 
52
+ /**
53
+ * Pluggable logger interface and default implementation.
54
+ * LOG-001 / Decision #14
55
+ */
56
+ interface DatafnLogger {
57
+ info(message: string, context?: Record<string, unknown>): void;
58
+ warn(message: string, context?: Record<string, unknown>): void;
59
+ error(message: string, context?: Record<string, unknown>): void;
60
+ debug(message: string, context?: Record<string, unknown>): void;
61
+ }
62
+
195
63
  interface SearchResultItem {
196
64
  id: string;
197
65
  resource: string;
@@ -215,6 +83,56 @@ interface CrossResourceSearchParams {
215
83
  signal?: AbortSignal;
216
84
  }
217
85
 
86
+ /**
87
+ * Execution Timing Middleware (OBS-001 through OBS-004)
88
+ * Provides structured phase-level timing for query, mutation, and sync operations.
89
+ */
90
+ /**
91
+ * Timing event emitted after each operation completes.
92
+ * Contains phase-by-phase duration breakdown.
93
+ * MUST NOT include record data, filter values, or credentials.
94
+ */
95
+ interface ExecutionTimingEvent {
96
+ endpoint: string;
97
+ resource?: string;
98
+ operation?: string;
99
+ phases: Record<string, number>;
100
+ totalMs: number;
101
+ timestamp: string;
102
+ }
103
+
104
+ interface RetentionConfig {
105
+ /** Number of days to retain change log entries. Default: unlimited. */
106
+ changeLogDays?: number;
107
+ /** Number of days to retain idempotency records. Default: unlimited. */
108
+ idempotencyDays?: number;
109
+ /** Whether to run pruning on server startup. Default: false. */
110
+ pruneOnStartup?: boolean;
111
+ /** Interval in milliseconds for periodic pruning. Minimum: 60000. Default: disabled. */
112
+ pruneIntervalMs?: number;
113
+ }
114
+ interface RateLimitConfig<TContext = any> {
115
+ /** Enable rate limiting. Default: false. */
116
+ enabled: boolean;
117
+ /** Max requests per window per client. Default: 100. */
118
+ maxRequests?: number;
119
+ /** Window duration in seconds. Default: 60. */
120
+ windowSeconds?: number;
121
+ /** Per-endpoint overrides */
122
+ endpoints?: Partial<Record<'query' | 'mutation' | 'transact' | 'push' | 'pull' | 'clone' | 'reconcile' | 'seed', {
123
+ maxRequests: number;
124
+ windowSeconds: number;
125
+ }>>;
126
+ /** Key extractor for identifying clients. Default: uses authContext userId or "anonymous". */
127
+ keyExtractor?: (ctx: TContext) => string | Promise<string>;
128
+ }
129
+ interface ObservabilityConfig {
130
+ /** Emit execution timing events. Default: false. */
131
+ timing?: boolean;
132
+ /** Custom timing event handler. Default: console.debug. */
133
+ onTiming?: (event: ExecutionTimingEvent) => void;
134
+ }
135
+
218
136
  /**
219
137
  * SequenceStore - Pluggable sequence generation for serverSeq
220
138
  *
@@ -386,6 +304,8 @@ interface DatafnServerConfig<TContext = any> {
386
304
  plugins?: DatafnPlugin[];
387
305
  /** Optional authorization callback */
388
306
  authorize?: (ctx: TContext, action: "status" | "query" | "mutation" | "transact" | "seed" | "clone" | "pull" | "push" | "reconcile" | "search", payload: unknown) => Promise<boolean> | boolean;
307
+ /** Optional request context factory passed through to namespace, actor, auth, and route handlers. */
308
+ context?: TContext | ((request: Request) => Promise<TContext> | TContext);
389
309
  /** Optional limits configuration */
390
310
  limits?: {
391
311
  maxLimit?: number;
@@ -447,7 +367,7 @@ interface DatafnServerConfig<TContext = any> {
447
367
  namespaceProvider?: {
448
368
  getNamespace: (ctx: TContext) => string | Promise<string>;
449
369
  /** Optional actor ID for audit attribution (separate from isolation). */
450
- getActorId?: (ctx: TContext) => string | Promise<string>;
370
+ getActorId?: (ctx: TContext) => string | undefined | Promise<string | undefined>;
451
371
  };
452
372
  /**
453
373
  * Optional Redis adapter for atomic operations (serverSeq, rate limiting, caching).
package/dist/index.d.ts CHANGED
@@ -1,149 +1,6 @@
1
+ import { DatafnSchema, DatafnPlugin } from '@datafn/core/types';
1
2
  import { Router } from '@superfunctions/http';
2
- import { Adapter, RedisAdapter, KVStoreAdapter, RowLevelNamespaceConfig } from '@superfunctions/db';
3
-
4
- /**
5
- * Pluggable logger interface and default implementation.
6
- * LOG-001 / Decision #14
7
- */
8
- interface DatafnLogger {
9
- info(message: string, context?: Record<string, unknown>): void;
10
- warn(message: string, context?: Record<string, unknown>): void;
11
- error(message: string, context?: Record<string, unknown>): void;
12
- debug(message: string, context?: Record<string, unknown>): void;
13
- }
14
-
15
- /**
16
- * Execution Timing Middleware (OBS-001 through OBS-004)
17
- * Provides structured phase-level timing for query, mutation, and sync operations.
18
- */
19
- /**
20
- * Timing event emitted after each operation completes.
21
- * Contains phase-by-phase duration breakdown.
22
- * MUST NOT include record data, filter values, or credentials.
23
- */
24
- interface ExecutionTimingEvent {
25
- endpoint: string;
26
- resource?: string;
27
- operation?: string;
28
- phases: Record<string, number>;
29
- totalMs: number;
30
- timestamp: string;
31
- }
32
-
33
- type DatafnPermissionsPolicy = {
34
- read?: {
35
- fields: string[];
36
- };
37
- write?: {
38
- fields: string[];
39
- };
40
- ownerField?: string;
41
- };
42
- type DatafnFieldSchema = {
43
- name: string;
44
- type: "string" | "number" | "boolean" | "object" | "array" | "date" | "file" | "json";
45
- required?: boolean;
46
- nullable?: boolean;
47
- readonly?: boolean;
48
- default?: unknown;
49
- enum?: unknown[];
50
- min?: number;
51
- max?: number;
52
- minLength?: number;
53
- maxLength?: number;
54
- pattern?: string;
55
- unique?: boolean | string;
56
- encrypt?: boolean;
57
- volatile?: boolean;
58
- };
59
- type DatafnResourceSchema = {
60
- name: string;
61
- version: number;
62
- idPrefix?: string;
63
- isRemoteOnly?: boolean;
64
- fields: DatafnFieldSchema[];
65
- indices?: {
66
- base?: string[];
67
- search?: string[];
68
- vector?: string[];
69
- } | string[];
70
- permissions?: DatafnPermissionsPolicy;
71
- capabilities?: unknown;
72
- };
73
- type DatafnRelationSchema = {
74
- from: string | string[];
75
- to: string | string[];
76
- type: "one-many" | "many-one" | "many-many" | "htree";
77
- relation?: string;
78
- inverse?: string;
79
- cache?: boolean;
80
- metadata?: Array<{
81
- name: string;
82
- type: "string" | "number" | "boolean" | "date" | "object" | "json";
83
- }>;
84
- fkField?: string;
85
- pathField?: string;
86
- joinTable?: string;
87
- joinColumns?: {
88
- from: string;
89
- to: string;
90
- };
91
- /** Relation-level capabilities (e.g. "timestamps", "audit") for many-many join rows. */
92
- capabilities?: string[];
93
- };
94
- type DatafnSchema = {
95
- version?: number;
96
- capabilities?: unknown;
97
- resources: DatafnResourceSchema[];
98
- relations?: DatafnRelationSchema[];
99
- namespaced?: boolean;
100
- };
101
- type DatafnHookContext = {
102
- env: "client" | "server";
103
- schema: DatafnSchema;
104
- context?: unknown;
105
- };
106
- type DatafnPlugin = {
107
- name: string;
108
- runsOn: Array<"client" | "server">;
109
- beforeQuery?: (ctx: DatafnHookContext, q: unknown) => Promise<unknown> | unknown;
110
- afterQuery?: (ctx: DatafnHookContext, q: unknown, result: unknown) => Promise<unknown> | unknown;
111
- beforeMutation?: (ctx: DatafnHookContext, m: unknown | unknown[]) => Promise<unknown> | unknown;
112
- afterMutation?: (ctx: DatafnHookContext, m: unknown | unknown[], result: unknown) => Promise<void> | void;
113
- beforeSync?: (ctx: DatafnHookContext, phase: "seed" | "clone" | "pull" | "push" | "cloneUp" | "reconcile", payload: unknown) => Promise<unknown> | unknown;
114
- afterSync?: (ctx: DatafnHookContext, phase: "seed" | "clone" | "pull" | "push" | "cloneUp" | "reconcile", payload: unknown, result: unknown) => Promise<void> | void;
115
- };
116
- interface RetentionConfig {
117
- /** Number of days to retain change log entries. Default: unlimited. */
118
- changeLogDays?: number;
119
- /** Number of days to retain idempotency records. Default: unlimited. */
120
- idempotencyDays?: number;
121
- /** Whether to run pruning on server startup. Default: false. */
122
- pruneOnStartup?: boolean;
123
- /** Interval in milliseconds for periodic pruning. Minimum: 60000. Default: disabled. */
124
- pruneIntervalMs?: number;
125
- }
126
- interface RateLimitConfig<TContext = any> {
127
- /** Enable rate limiting. Default: false. */
128
- enabled: boolean;
129
- /** Max requests per window per client. Default: 100. */
130
- maxRequests?: number;
131
- /** Window duration in seconds. Default: 60. */
132
- windowSeconds?: number;
133
- /** Per-endpoint overrides */
134
- endpoints?: Partial<Record<'query' | 'mutation' | 'transact' | 'push' | 'pull' | 'clone' | 'reconcile' | 'seed', {
135
- maxRequests: number;
136
- windowSeconds: number;
137
- }>>;
138
- /** Key extractor for identifying clients. Default: uses authContext userId or "anonymous". */
139
- keyExtractor?: (ctx: TContext) => string | Promise<string>;
140
- }
141
- interface ObservabilityConfig {
142
- /** Emit execution timing events. Default: false. */
143
- timing?: boolean;
144
- /** Custom timing event handler. Default: console.debug. */
145
- onTiming?: (event: ExecutionTimingEvent) => void;
146
- }
3
+ import { Adapter, KVStoreAdapter, RedisAdapter, RowLevelNamespaceConfig } from '@superfunctions/db';
147
4
 
148
5
  /**
149
6
  * SearchProvider interface for server-side search integration.
@@ -192,6 +49,17 @@ interface SearchProvider {
192
49
  dispose?(): Promise<void>;
193
50
  }
194
51
 
52
+ /**
53
+ * Pluggable logger interface and default implementation.
54
+ * LOG-001 / Decision #14
55
+ */
56
+ interface DatafnLogger {
57
+ info(message: string, context?: Record<string, unknown>): void;
58
+ warn(message: string, context?: Record<string, unknown>): void;
59
+ error(message: string, context?: Record<string, unknown>): void;
60
+ debug(message: string, context?: Record<string, unknown>): void;
61
+ }
62
+
195
63
  interface SearchResultItem {
196
64
  id: string;
197
65
  resource: string;
@@ -215,6 +83,56 @@ interface CrossResourceSearchParams {
215
83
  signal?: AbortSignal;
216
84
  }
217
85
 
86
+ /**
87
+ * Execution Timing Middleware (OBS-001 through OBS-004)
88
+ * Provides structured phase-level timing for query, mutation, and sync operations.
89
+ */
90
+ /**
91
+ * Timing event emitted after each operation completes.
92
+ * Contains phase-by-phase duration breakdown.
93
+ * MUST NOT include record data, filter values, or credentials.
94
+ */
95
+ interface ExecutionTimingEvent {
96
+ endpoint: string;
97
+ resource?: string;
98
+ operation?: string;
99
+ phases: Record<string, number>;
100
+ totalMs: number;
101
+ timestamp: string;
102
+ }
103
+
104
+ interface RetentionConfig {
105
+ /** Number of days to retain change log entries. Default: unlimited. */
106
+ changeLogDays?: number;
107
+ /** Number of days to retain idempotency records. Default: unlimited. */
108
+ idempotencyDays?: number;
109
+ /** Whether to run pruning on server startup. Default: false. */
110
+ pruneOnStartup?: boolean;
111
+ /** Interval in milliseconds for periodic pruning. Minimum: 60000. Default: disabled. */
112
+ pruneIntervalMs?: number;
113
+ }
114
+ interface RateLimitConfig<TContext = any> {
115
+ /** Enable rate limiting. Default: false. */
116
+ enabled: boolean;
117
+ /** Max requests per window per client. Default: 100. */
118
+ maxRequests?: number;
119
+ /** Window duration in seconds. Default: 60. */
120
+ windowSeconds?: number;
121
+ /** Per-endpoint overrides */
122
+ endpoints?: Partial<Record<'query' | 'mutation' | 'transact' | 'push' | 'pull' | 'clone' | 'reconcile' | 'seed', {
123
+ maxRequests: number;
124
+ windowSeconds: number;
125
+ }>>;
126
+ /** Key extractor for identifying clients. Default: uses authContext userId or "anonymous". */
127
+ keyExtractor?: (ctx: TContext) => string | Promise<string>;
128
+ }
129
+ interface ObservabilityConfig {
130
+ /** Emit execution timing events. Default: false. */
131
+ timing?: boolean;
132
+ /** Custom timing event handler. Default: console.debug. */
133
+ onTiming?: (event: ExecutionTimingEvent) => void;
134
+ }
135
+
218
136
  /**
219
137
  * SequenceStore - Pluggable sequence generation for serverSeq
220
138
  *
@@ -386,6 +304,8 @@ interface DatafnServerConfig<TContext = any> {
386
304
  plugins?: DatafnPlugin[];
387
305
  /** Optional authorization callback */
388
306
  authorize?: (ctx: TContext, action: "status" | "query" | "mutation" | "transact" | "seed" | "clone" | "pull" | "push" | "reconcile" | "search", payload: unknown) => Promise<boolean> | boolean;
307
+ /** Optional request context factory passed through to namespace, actor, auth, and route handlers. */
308
+ context?: TContext | ((request: Request) => Promise<TContext> | TContext);
389
309
  /** Optional limits configuration */
390
310
  limits?: {
391
311
  maxLimit?: number;
@@ -447,7 +367,7 @@ interface DatafnServerConfig<TContext = any> {
447
367
  namespaceProvider?: {
448
368
  getNamespace: (ctx: TContext) => string | Promise<string>;
449
369
  /** Optional actor ID for audit attribution (separate from isolation). */
450
- getActorId?: (ctx: TContext) => string | Promise<string>;
370
+ getActorId?: (ctx: TContext) => string | undefined | Promise<string | undefined>;
451
371
  };
452
372
  /**
453
373
  * Optional Redis adapter for atomic operations (serverSeq, rate limiting, caching).