@toolproof-npm/shared 0.1.78 → 0.1.80

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.
Files changed (6) hide show
  1. package/dist/_lib/types.d.ts +3 -8
  2. package/dist/_lib/utils/resourceCreation.d.ts +24 -77
  3. package/dist/_lib/utils/resourceCreation.js +35 -91
  4. package/dist/constants.d.ts +1 -1
  5. package/dist/constants.js +1 -1
  6. package/package.json +1 -1
package/dist/_lib/types.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { ExecutionIdentityJson, ResourceIdentityJson, ResourceJson, ResourceRoleIdentityJson, ResourceRoleValueJson, ResourceTypeIdentityJson } from '@toolproof-npm/schema';
1
+ import type { ResourceJson, ResourceRoleIdentityJson, ResourceRoleValueJson, ResourceTypeIdentityJson } from '@toolproof-npm/schema';
2
2
  import { CONSTANTS } from '../constants.js';
3
3
  export type BucketConst = typeof CONSTANTS.STORAGE.BUCKETS.tp_resources;
4
4
  export type CollectionConst = keyof typeof CONSTANTS.STORAGE.COLLECTIONS;
@@ -8,12 +8,7 @@ export type Role = {
8
8
  identity: ResourceRoleIdentityJson;
9
9
  } & ResourceRoleValueJson;
10
10
  export type ResourceMap = Record<ResourceTypeIdentityJson, ResourceJson[]>;
11
- export type PartialResourceMeta = {
12
- identity: ResourceIdentityJson;
13
- resourceTypeRef: ResourceTypeIdentityJson;
14
- creationContext: {
15
- resourceRoleRef: ResourceRoleIdentityJson;
16
- executionRef: ExecutionIdentityJson;
17
- };
11
+ export type PartialResourceMeta = Omit<ResourceJson, 'kind' | 'timestamp' | 'path'> & {
12
+ /** Optional timestamp (for replacing existing resources with same timestamp) */
18
13
  timestamp?: string;
19
14
  };
package/dist/_lib/utils/resourceCreation.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import type { ResourceTypeIdentityJson, ResourceJson, ResourcePotentialOutputJson, JsonDataJson } from '@toolproof-npm/schema';
2
+ import type { PartialResourceMeta } from '../types.js';
2
3
  /**
3
4
  * Generates SHA-256 hash of content
4
5
  * @param content The content to hash
@@ -12,101 +13,47 @@ export declare function generateContentHash(content: string): string;
12
13
  * @returns The path in format: {resourceTypeRef}/{contentHash}
13
14
  */
14
15
  export declare function generateContentAddressedPath(resourceTypeRef: ResourceTypeIdentityJson, content: string): string;
15
- /**
16
- * Options for creating a materialized resource from a potential-output
17
- * Provide either 'path' OR 'content' (which generates a hash-based path)
18
- */
19
- export type CreateMaterializedResourceOptions = Pick<ResourceJson, 'extractedData'> & {
20
- /** Explicit path (if provided, content is ignored) */
21
- path?: string;
22
- /** Content to hash for generating path (used if path not provided) */
23
- content?: string;
24
- /** Optional timestamp (defaults to current ISO timestamp) */
25
- timestamp?: string;
26
- };
27
- /**
28
- * Options for creating a materialized resource from scratch
29
- * Provide either 'path' OR 'content' (which generates a hash-based path)
30
- * Omits 'kind' (always set to 'materialized') and makes 'timestamp' optional
31
- */
32
- export type CreateMaterializedResourceFromScratchOptions = Omit<ResourceJson, 'kind' | 'timestamp' | 'path'> & {
33
- /** Explicit path (if provided, content is ignored) */
34
- path?: string;
35
- /** Content to hash for generating path (used if path not provided) */
36
- content?: string;
37
- /** Optional timestamp (defaults to current ISO timestamp) */
38
- timestamp?: string;
39
- };
40
16
  /**
41
17
  * Creates a materialized resource from a potential-output resource.
42
- * Handles timestamp generation, extractedData normalization, path generation, and structural conversion.
18
+ * Converts the potential output to a materialized resource by generating a content-addressed path,
19
+ * assigning the content as extractedData, and creating a timestamp.
43
20
  *
44
21
  * @param potentialOutput The potential-output resource to materialize
45
- * @param options Configuration for the materialized resource
22
+ * @param content The actual content produced by the job (assigned directly to extractedData)
46
23
  * @returns A fully materialized ResourceJson
47
24
  *
48
25
  * @example
49
26
  * ```typescript
50
- * // With explicit path
51
- * const materialized = createMaterializedResource(potentialOutput, {
52
- * path: 'TYPE-Natural/abc123...',
53
- * extractedData: { identity: 42 },
54
- * timestamp: '2025-01-03T12:00:00.000Z'
55
- * });
56
- *
57
- * // With content (generates hash-based path)
58
- * const materialized = createMaterializedResource(potentialOutput, {
59
- * content: '{"identity": 42}',
60
- * extractedData: { identity: 42 }
61
- * });
27
+ * const materialized = createMaterializedResourceFromPotentialOutput(
28
+ * potentialOutput,
29
+ * { identity: 42, someData: "result" }
30
+ * );
62
31
  * ```
63
32
  */
64
- export declare function createMaterializedResource(potentialOutput: ResourcePotentialOutputJson, options: CreateMaterializedResourceOptions): ResourceJson;
65
- /**
66
- * Normalizes extractedData to ensure consistent structure with an identity field.
67
- * Handles various input formats:
68
- * - Primitives (numbers, strings): wrapped in { identity: value }
69
- * - Objects with identity: preserved
70
- * - Objects without identity: identity extracted from first suitable field
71
- *
72
- * @param data The raw extracted data
73
- * @returns Normalized extractedData with identity field
74
- */
75
- export declare function normalizeExtractedData(data: JsonDataJson): JsonDataJson;
33
+ export declare function createMaterializedResourceFromPotentialOutput(potentialOutput: ResourcePotentialOutputJson, content: JsonDataJson): ResourceJson;
76
34
  /**
77
35
  * Creates a materialized resource from scratch (for manual resource creation).
78
- * Handles timestamp generation, extractedData normalization, path generation, and structural validation.
36
+ * Generates a content-addressed path from the content and creates a timestamp.
79
37
  * Use this when creating resources manually without a potential-output template.
80
38
  *
81
- * @param options All required fields for creating a materialized resource
39
+ * @param partialResourceMeta Partial metadata (identity, type, context, optional timestamp)
40
+ * @param content The actual content/data (assigned directly to extractedData)
82
41
  * @returns A fully materialized ResourceJson
83
42
  *
84
43
  * @example
85
44
  * ```typescript
86
- * // With explicit path
87
- * const materialized = createMaterializedResourceFromScratch({
88
- * identity: 'RESOURCE-abc123',
89
- * resourceTypeRef: 'TYPE-Natural',
90
- * creationContext: {
91
- * resourceRoleRef: 'ROLE-Manual',
92
- * executionRef: 'EXECUTION-Genesis'
93
- * },
94
- * path: 'TYPE-Natural/def456...',
95
- * extractedData: { identity: 42 },
96
- * timestamp: '2025-01-03T12:00:00.000Z'
97
- * });
98
- *
99
- * // With content (generates hash-based path)
100
- * const materialized = createMaterializedResourceFromScratch({
101
- * identity: 'RESOURCE-abc123',
102
- * resourceTypeRef: 'TYPE-Natural',
103
- * creationContext: {
104
- * resourceRoleRef: 'ROLE-Manual',
105
- * executionRef: 'EXECUTION-Genesis'
45
+ * const materialized = createMaterializedResourceFromScratch(
46
+ * {
47
+ * identity: 'RESOURCE-abc123',
48
+ * resourceTypeRef: 'TYPE-Natural',
49
+ * creationContext: {
50
+ * resourceRoleRef: 'ROLE-Manual',
51
+ * executionRef: 'EXECUTION-Genesis'
52
+ * },
53
+ * timestamp: '2025-01-03T12:00:00.000Z' // optional
106
54
  * },
107
- * content: '{"identity": 42}',
108
- * extractedData: { identity: 42 }
109
- * });
55
+ * { identity: 42 }
56
+ * );
110
57
  * ```
111
58
  */
112
- export declare function createMaterializedResourceFromScratch(options: CreateMaterializedResourceFromScratchOptions): ResourceJson;
59
+ export declare function createMaterializedResourceFromScratch(partialResourceMeta: PartialResourceMeta, content: JsonDataJson): ResourceJson;
package/dist/_lib/utils/resourceCreation.js CHANGED
@@ -19,128 +19,72 @@ export function generateContentAddressedPath(resourceTypeRef, content) {
19
19
  }
20
20
  /**
21
21
  * Creates a materialized resource from a potential-output resource.
22
- * Handles timestamp generation, extractedData normalization, path generation, and structural conversion.
22
+ * Converts the potential output to a materialized resource by generating a content-addressed path,
23
+ * assigning the content as extractedData, and creating a timestamp.
23
24
  *
24
25
  * @param potentialOutput The potential-output resource to materialize
25
- * @param options Configuration for the materialized resource
26
+ * @param content The actual content produced by the job (assigned directly to extractedData)
26
27
  * @returns A fully materialized ResourceJson
27
28
  *
28
29
  * @example
29
30
  * ```typescript
30
- * // With explicit path
31
- * const materialized = createMaterializedResource(potentialOutput, {
32
- * path: 'TYPE-Natural/abc123...',
33
- * extractedData: { identity: 42 },
34
- * timestamp: '2025-01-03T12:00:00.000Z'
35
- * });
36
- *
37
- * // With content (generates hash-based path)
38
- * const materialized = createMaterializedResource(potentialOutput, {
39
- * content: '{"identity": 42}',
40
- * extractedData: { identity: 42 }
41
- * });
31
+ * const materialized = createMaterializedResourceFromPotentialOutput(
32
+ * potentialOutput,
33
+ * { identity: 42, someData: "result" }
34
+ * );
42
35
  * ```
43
36
  */
44
- export function createMaterializedResource(potentialOutput, options) {
45
- const { path, content, extractedData, timestamp } = options;
46
- // Determine path: use explicit path or generate from content
47
- const finalPath = path ?? (content ? generateContentAddressedPath(potentialOutput.resourceTypeRef, content) : '');
48
- if (!finalPath) {
49
- throw new Error('Either path or content must be provided');
50
- }
51
- // Normalize extractedData to ensure it has an identity field
52
- const normalizedExtractedData = normalizeExtractedData(extractedData);
37
+ export function createMaterializedResourceFromPotentialOutput(potentialOutput, content) {
38
+ // Generate content-addressed path from the content
39
+ const contentString = JSON.stringify(content);
40
+ const path = generateContentAddressedPath(potentialOutput.resourceTypeRef, contentString);
53
41
  return {
54
42
  identity: potentialOutput.identity,
55
43
  resourceTypeRef: potentialOutput.resourceTypeRef,
56
44
  creationContext: potentialOutput.creationContext,
57
45
  kind: 'materialized',
58
- path: finalPath,
59
- timestamp: timestamp ?? new Date().toISOString(),
60
- extractedData: normalizedExtractedData,
61
- };
62
- }
63
- /**
64
- * Normalizes extractedData to ensure consistent structure with an identity field.
65
- * Handles various input formats:
66
- * - Primitives (numbers, strings): wrapped in { identity: value }
67
- * - Objects with identity: preserved
68
- * - Objects without identity: identity extracted from first suitable field
69
- *
70
- * @param data The raw extracted data
71
- * @returns Normalized extractedData with identity field
72
- */
73
- export function normalizeExtractedData(data) {
74
- // If data is a primitive, wrap it
75
- if (typeof data !== 'object' || data === null) {
76
- return { identity: data };
77
- }
78
- // If data is an object
79
- const dataObj = data;
80
- // If it already has an identity field, preserve everything
81
- if ('identity' in dataObj) {
82
- return data;
83
- }
84
- // Otherwise, try to extract an identity value from common patterns
85
- // This handles cases where the data might have a value field or similar
86
- const identityValue = dataObj.value ?? dataObj.id ?? dataObj.result ?? 0;
87
- return {
88
- identity: identityValue,
89
- ...dataObj,
46
+ path,
47
+ timestamp: new Date().toISOString(),
48
+ extractedData: content,
90
49
  };
91
50
  }
92
51
  /**
93
52
  * Creates a materialized resource from scratch (for manual resource creation).
94
- * Handles timestamp generation, extractedData normalization, path generation, and structural validation.
53
+ * Generates a content-addressed path from the content and creates a timestamp.
95
54
  * Use this when creating resources manually without a potential-output template.
96
55
  *
97
- * @param options All required fields for creating a materialized resource
56
+ * @param partialResourceMeta Partial metadata (identity, type, context, optional timestamp)
57
+ * @param content The actual content/data (assigned directly to extractedData)
98
58
  * @returns A fully materialized ResourceJson
99
59
  *
100
60
  * @example
101
61
  * ```typescript
102
- * // With explicit path
103
- * const materialized = createMaterializedResourceFromScratch({
104
- * identity: 'RESOURCE-abc123',
105
- * resourceTypeRef: 'TYPE-Natural',
106
- * creationContext: {
107
- * resourceRoleRef: 'ROLE-Manual',
108
- * executionRef: 'EXECUTION-Genesis'
109
- * },
110
- * path: 'TYPE-Natural/def456...',
111
- * extractedData: { identity: 42 },
112
- * timestamp: '2025-01-03T12:00:00.000Z'
113
- * });
114
- *
115
- * // With content (generates hash-based path)
116
- * const materialized = createMaterializedResourceFromScratch({
117
- * identity: 'RESOURCE-abc123',
118
- * resourceTypeRef: 'TYPE-Natural',
119
- * creationContext: {
120
- * resourceRoleRef: 'ROLE-Manual',
121
- * executionRef: 'EXECUTION-Genesis'
62
+ * const materialized = createMaterializedResourceFromScratch(
63
+ * {
64
+ * identity: 'RESOURCE-abc123',
65
+ * resourceTypeRef: 'TYPE-Natural',
66
+ * creationContext: {
67
+ * resourceRoleRef: 'ROLE-Manual',
68
+ * executionRef: 'EXECUTION-Genesis'
69
+ * },
70
+ * timestamp: '2025-01-03T12:00:00.000Z' // optional
122
71
  * },
123
- * content: '{"identity": 42}',
124
- * extractedData: { identity: 42 }
125
- * });
72
+ * { identity: 42 }
73
+ * );
126
74
  * ```
127
75
  */
128
- export function createMaterializedResourceFromScratch(options) {
129
- const { identity, resourceTypeRef, creationContext, path, content, extractedData, timestamp } = options;
130
- // Determine path: use explicit path or generate from content
131
- const finalPath = path ?? (content ? generateContentAddressedPath(resourceTypeRef, content) : '');
132
- if (!finalPath) {
133
- throw new Error('Either path or content must be provided');
134
- }
135
- // Normalize extractedData to ensure it has an identity field
136
- const normalizedExtractedData = normalizeExtractedData(extractedData);
76
+ export function createMaterializedResourceFromScratch(partialResourceMeta, content) {
77
+ const { identity, resourceTypeRef, creationContext, timestamp } = partialResourceMeta;
78
+ // Generate content-addressed path from the content
79
+ const contentString = JSON.stringify(content);
80
+ const path = generateContentAddressedPath(resourceTypeRef, contentString);
137
81
  return {
138
82
  identity,
139
83
  resourceTypeRef,
140
84
  creationContext,
141
85
  kind: 'materialized',
142
- path: finalPath,
86
+ path,
143
87
  timestamp: timestamp ?? new Date().toISOString(),
144
- extractedData: normalizedExtractedData,
88
+ extractedData: content,
145
89
  };
146
90
  }
package/dist/constants.d.ts CHANGED
@@ -19,7 +19,7 @@ export declare const CONSTANTS: {
19
19
  readonly type: "type";
20
20
  readonly role: "role";
21
21
  readonly job: "job";
22
- readonly execution: "executions";
22
+ readonly execution: "execution";
23
23
  readonly resource: "resource";
24
24
  readonly stateless_strategy: "stateless_strategy";
25
25
  readonly stateful_strategy: "stateful_strategy";
package/dist/constants.js CHANGED
@@ -19,7 +19,7 @@ export const CONSTANTS = {
19
19
  type: 'type',
20
20
  role: 'role',
21
21
  job: 'job',
22
- execution: 'executions',
22
+ execution: 'execution',
23
23
  resource: 'resource',
24
24
  stateless_strategy: 'stateless_strategy',
25
25
  stateful_strategy: 'stateful_strategy',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@toolproof-npm/shared",
3
- "version": "0.1.78",
3
+ "version": "0.1.80",
4
4
  "description": "Core library utilities for ToolProof",
5
5
  "keywords": [
6
6
  "toolproof",