@ankhorage/contracts 1.15.0 → 1.16.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @ankhorage/contracts
 
+## 1.16.0
+
+### Minor Changes
+
+- 5105c41: Add API authoring contracts for generated and external APIs with explicit endpoints, generated CRUD presets, and collection-backed resources.
+
 ## 1.15.0
 
 ### Minor Changes

package/dist/data/apis.d.ts

@@ -0,0 +1,76 @@
+import type { DbCollectionDefinition } from '../db';
+import type { DataOperationRequest, DataOperationResponse } from './operations';
+import type { DataContractValue } from './values';
+export declare const APP_API_KINDS: readonly ["external", "generated"];
+export type AppApiKind = (typeof APP_API_KINDS)[number];
+export declare const APP_API_GENERATED_PRESETS: readonly ["crud"];
+export type AppApiGeneratedPreset = (typeof APP_API_GENERATED_PRESETS)[number];
+export declare const APP_API_ENDPOINT_METHODS: readonly ["DELETE", "GET", "HEAD", "OPTIONS", "PATCH", "POST", "PUT"];
+export type AppApiEndpointMethod = (typeof APP_API_ENDPOINT_METHODS)[number];
+export declare const APP_API_ENDPOINT_INTENTS: readonly ["create", "custom", "delete", "list", "read", "update"];
+export type AppApiEndpointIntent = (typeof APP_API_ENDPOINT_INTENTS)[number];
+export type AppApiId = string;
+export type AppApiEndpointId = string;
+export type AppApiSeedRecord = Readonly<Record<string, DataContractValue>>;
+export interface AppApiAuthRequirement {
+    readonly required?: boolean;
+    readonly roles?: readonly string[];
+    readonly permissions?: readonly string[];
+    readonly policy?: string;
+    readonly metadata?: DataContractValue;
+}
+export interface AppApiCollectionResourceDefinition {
+    readonly kind: 'collection';
+    readonly collection: DbCollectionDefinition;
+    readonly seed?: readonly AppApiSeedRecord[];
+    readonly metadata?: DataContractValue;
+}
+export type AppApiResourceDefinition = AppApiCollectionResourceDefinition;
+export interface AppApiEndpointDefinition {
+    readonly id: AppApiEndpointId;
+    readonly label?: string;
+    readonly description?: string;
+    readonly method: AppApiEndpointMethod;
+    /**
+     * Path relative to the API base path. Use `/` for the base collection endpoint.
+     */
+    readonly path: string;
+    readonly intent?: AppApiEndpointIntent;
+    readonly request?: DataOperationRequest;
+    readonly response?: DataOperationResponse;
+    readonly auth?: AppApiAuthRequirement;
+    readonly metadata?: DataContractValue;
+}
+interface AppApiDefinitionBase {
+    readonly id: AppApiId;
+    readonly kind: AppApiKind;
+    readonly label?: string;
+    readonly description?: string;
+    readonly basePath: string;
+    readonly endpoints: readonly AppApiEndpointDefinition[];
+    readonly auth?: AppApiAuthRequirement;
+    readonly metadata?: DataContractValue;
+}
+export interface AppGeneratedApiDefinition extends AppApiDefinitionBase {
+    readonly kind: 'generated';
+    /**
+     * Preset used by authoring tools to seed standard endpoints. The resulting
+     * serialized API still stores concrete `endpoints[]` so custom endpoints can
+     * live next to generated CRUD operations.
+     */
+    readonly preset?: AppApiGeneratedPreset;
+    readonly resource?: AppApiResourceDefinition;
+}
+export interface AppExternalApiDefinition extends AppApiDefinitionBase {
+    readonly kind: 'external';
+    readonly baseUrl?: string;
+    readonly openApiUrl?: string;
+}
+export type AppApiDefinition = AppExternalApiDefinition | AppGeneratedApiDefinition;
+export type AppApiRegistry = Readonly<Record<AppApiId, AppApiDefinition>>;
+export interface AppDataManifest {
+    readonly apis?: AppApiRegistry;
+}
+export type AppApiManifest = AppDataManifest;
+export {};
+//# sourceMappingURL=apis.d.ts.map

package/dist/data/apis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apis.d.ts","sourceRoot":"","sources":["../../src/data/apis.ts"],"names":[],"mappings":"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"}

package/dist/data/apis.js

@@ -0,0 +1,20 @@
+export const APP_API_KINDS = ['external', 'generated'];
+export const APP_API_GENERATED_PRESETS = ['crud'];
+export const APP_API_ENDPOINT_METHODS = [
+    'DELETE',
+    'GET',
+    'HEAD',
+    'OPTIONS',
+    'PATCH',
+    'POST',
+    'PUT',
+];
+export const APP_API_ENDPOINT_INTENTS = [
+    'create',
+    'custom',
+    'delete',
+    'list',
+    'read',
+    'update',
+];
+//# sourceMappingURL=apis.js.map

package/dist/data/apis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apis.js","sourceRoot":"","sources":["../../src/data/apis.ts"],"names":[],"mappings":"AAIA,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,UAAU,EAAE,WAAW,CAAU,CAAC;AAGhE,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,MAAM,CAAU,CAAC;AAG3D,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,QAAQ;IACR,KAAK;IACL,MAAM;IACN,SAAS;IACT,OAAO;IACP,MAAM;IACN,KAAK;CACG,CAAC;AAGX,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,MAAM;IACN,MAAM;IACN,QAAQ;CACA,CAAC","sourcesContent":["import type { DbCollectionDefinition } from '../db';\nimport type { DataOperationRequest, DataOperationResponse } from './operations';\nimport type { DataContractValue } from './values';\n\nexport const APP_API_KINDS = ['external', 'generated'] as const;\nexport type AppApiKind = (typeof APP_API_KINDS)[number];\n\nexport const APP_API_GENERATED_PRESETS = ['crud'] as const;\nexport type AppApiGeneratedPreset = (typeof APP_API_GENERATED_PRESETS)[number];\n\nexport const APP_API_ENDPOINT_METHODS = [\n  'DELETE',\n  'GET',\n  'HEAD',\n  'OPTIONS',\n  'PATCH',\n  'POST',\n  'PUT',\n] as const;\nexport type AppApiEndpointMethod = (typeof APP_API_ENDPOINT_METHODS)[number];\n\nexport const APP_API_ENDPOINT_INTENTS = [\n  'create',\n  'custom',\n  'delete',\n  'list',\n  'read',\n  'update',\n] as const;\nexport type AppApiEndpointIntent = (typeof APP_API_ENDPOINT_INTENTS)[number];\n\nexport type AppApiId = string;\nexport type AppApiEndpointId = string;\nexport type AppApiSeedRecord = Readonly<Record<string, DataContractValue>>;\n\nexport interface AppApiAuthRequirement {\n  readonly required?: boolean;\n  readonly roles?: readonly string[];\n  readonly permissions?: readonly string[];\n  readonly policy?: string;\n  readonly metadata?: DataContractValue;\n}\n\nexport interface AppApiCollectionResourceDefinition {\n  readonly kind: 'collection';\n  readonly collection: DbCollectionDefinition;\n  readonly seed?: readonly AppApiSeedRecord[];\n  readonly metadata?: DataContractValue;\n}\n\nexport type AppApiResourceDefinition = AppApiCollectionResourceDefinition;\n\nexport interface AppApiEndpointDefinition {\n  readonly id: AppApiEndpointId;\n  readonly label?: string;\n  readonly description?: string;\n  readonly method: AppApiEndpointMethod;\n  /**\n   * Path relative to the API base path. Use `/` for the base collection endpoint.\n   */\n  readonly path: string;\n  readonly intent?: AppApiEndpointIntent;\n  readonly request?: DataOperationRequest;\n  readonly response?: DataOperationResponse;\n  readonly auth?: AppApiAuthRequirement;\n  readonly metadata?: DataContractValue;\n}\n\ninterface AppApiDefinitionBase {\n  readonly id: AppApiId;\n  readonly kind: AppApiKind;\n  readonly label?: string;\n  readonly description?: string;\n  readonly basePath: string;\n  readonly endpoints: readonly AppApiEndpointDefinition[];\n  readonly auth?: AppApiAuthRequirement;\n  readonly metadata?: DataContractValue;\n}\n\nexport interface AppGeneratedApiDefinition extends AppApiDefinitionBase {\n  readonly kind: 'generated';\n  /**\n   * Preset used by authoring tools to seed standard endpoints. The resulting\n   * serialized API still stores concrete `endpoints[]` so custom endpoints can\n   * live next to generated CRUD operations.\n   */\n  readonly preset?: AppApiGeneratedPreset;\n  readonly resource?: AppApiResourceDefinition;\n}\n\nexport interface AppExternalApiDefinition extends AppApiDefinitionBase {\n  readonly kind: 'external';\n  readonly baseUrl?: string;\n  readonly openApiUrl?: string;\n}\n\nexport type AppApiDefinition = AppExternalApiDefinition | AppGeneratedApiDefinition;\n\nexport type AppApiRegistry = Readonly<Record<AppApiId, AppApiDefinition>>;\n\nexport interface AppDataManifest {\n  readonly apis?: AppApiRegistry;\n}\n\nexport type AppApiManifest = AppDataManifest;\n"]}

package/dist/data/index.d.ts

@@ -1,4 +1,4 @@
-export * from './datasets';
+export * from './apis';
 export * from './diagnostics';
 export * from './endpoints';
 export * from './ids';

package/dist/data/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/data/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,OAAO,CAAC;AACtB,cAAc,cAAc,CAAC;AAC7B,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/data/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,OAAO,CAAC;AACtB,cAAc,cAAc,CAAC;AAC7B,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC"}

package/dist/data/index.js

@@ -1,4 +1,4 @@
-export * from './datasets';
+export * from './apis';
 export * from './diagnostics';
 export * from './endpoints';
 export * from './ids';

package/dist/data/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/data/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,OAAO,CAAC;AACtB,cAAc,cAAc,CAAC;AAC7B,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC","sourcesContent":["export * from './datasets';\nexport * from './diagnostics';\nexport * from './endpoints';\nexport * from './ids';\nexport * from './operations';\nexport * from './refs';\nexport * from './schemas';\nexport * from './sources';\nexport * from './values';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/data/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,OAAO,CAAC;AACtB,cAAc,cAAc,CAAC;AAC7B,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC","sourcesContent":["export * from './apis';\nexport * from './diagnostics';\nexport * from './endpoints';\nexport * from './ids';\nexport * from './operations';\nexport * from './refs';\nexport * from './schemas';\nexport * from './sources';\nexport * from './values';\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/contracts",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "main": "./dist/index.js",
   "dependencies": {
     "@ankhorage/color-theory": "^0.0.7"

package/src/contracts.test.ts

@@ -6,11 +6,7 @@ import { describe, expect, it } from 'bun:test';
 
 import {
   APP_CATEGORIES,
-  APP_DATASET_OPERATIONS,
   type AppCategory,
-  type AppDataManifest,
-  type AppDatasetDefinition,
-  type AppDatasetOperation,
   type AppManifest,
   AUTH_PROVIDERS,
   AUTH_SIGN_IN_IDENTIFIERS,
@@ -24,7 +20,6 @@ import {
   type DbAdapter,
   type DbAdminAdapter,
   type DbChangeEvent,
-  type DbCollectionDefinition,
   type DbRealtimeAdapter,
   DEPLOYMENT_TARGETS,
   type FormSubmitEventDto,
@@ -136,50 +131,6 @@ describe('contracts', () => {
     expect(JSON.parse(JSON.stringify(manifest))).toEqual({ splashScreen });
   });
 
-  it('accepts app-owned dataset manifests backed by db collection definitions', () => {
-    const operation: AppDatasetOperation = 'list';
-    const collection: DbCollectionDefinition = {
-      name: 'poker_situations',
-      primaryKey: 'id',
-      fields: [
-        { name: 'title', type: 'text', required: true },
-        { name: 'description', type: 'text', required: true },
-        { name: 'difficulty', type: 'text' },
-        { name: 'availableActions', type: 'json' },
-        { name: 'correctAction', type: 'text' },
-      ],
-    };
-    const dataset: AppDatasetDefinition = {
-      id: 'poker_situations',
-      label: 'Poker situations',
-      description: 'App-owned poker trainer situations.',
-      collection,
-      operations: [operation, 'read'],
-      seed: [
-        {
-          title: 'Button faces a raise',
-          description: 'Choose the best action with position and stack depth in mind.',
-          difficulty: 'beginner',
-          availableActions: [
-            { label: 'Fold', value: 'fold' },
-            { label: 'Call', value: 'call' },
-            { label: 'Raise', value: 'raise' },
-          ],
-          correctAction: 'raise',
-        },
-      ],
-    };
-    const data: AppDataManifest = {
-      datasets: {
-        [dataset.id]: dataset,
-      },
-    };
-    const manifest: Pick<AppManifest, 'data'> = { data };
-
-    expect(APP_DATASET_OPERATIONS).toEqual(['create', 'delete', 'list', 'read', 'update']);
-    expect(JSON.parse(JSON.stringify(manifest))).toEqual({ data });
-  });
-
   it('accepts provider-neutral state infra selection on app manifests', () => {
     const state: StateSpec = {
       provider: 'legend',

package/src/data/apis.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, test } from 'bun:test';
+
+import type {
+  AppApiDefinition,
+  AppApiEndpointDefinition,
+  AppApiManifest,
+  AppGeneratedApiDefinition,
+} from './apis';
+import { APP_API_ENDPOINT_INTENTS, APP_API_ENDPOINT_METHODS, APP_API_KINDS } from './apis';
+
+const crudEndpoints = [
+  {
+    id: 'players.list',
+    method: 'GET',
+    path: '/',
+    intent: 'list',
+  },
+  {
+    id: 'players.create',
+    method: 'POST',
+    path: '/',
+    intent: 'create',
+  },
+  {
+    id: 'players.read',
+    method: 'GET',
+    path: '/{id}',
+    intent: 'read',
+  },
+  {
+    id: 'players.update',
+    method: 'PATCH',
+    path: '/{id}',
+    intent: 'update',
+  },
+  {
+    id: 'players.delete',
+    method: 'DELETE',
+    path: '/{id}',
+    intent: 'delete',
+  },
+] satisfies readonly AppApiEndpointDefinition[];
+
+describe('app API authoring contracts', () => {
+  test('exports stable API authoring constants', () => {
+    expect(APP_API_KINDS).toEqual(['external', 'generated']);
+    expect(APP_API_ENDPOINT_METHODS).toEqual([
+      'DELETE',
+      'GET',
+      'HEAD',
+      'OPTIONS',
+      'PATCH',
+      'POST',
+      'PUT',
+    ]);
+    expect(APP_API_ENDPOINT_INTENTS).toEqual([
+      'create',
+      'custom',
+      'delete',
+      'list',
+      'read',
+      'update',
+    ]);
+  });
+
+  test('serializes generated APIs with a CRUD preset and explicit custom endpoints', () => {
+    const generatedApi: AppGeneratedApiDefinition = {
+      id: 'players',
+      kind: 'generated',
+      label: 'Players',
+      basePath: '/api/players',
+      preset: 'crud',
+      resource: {
+        kind: 'collection',
+        collection: {
+          name: 'players',
+          primaryKey: 'id',
+          fields: [
+            { name: 'id', type: 'uuid', required: true },
+            { name: 'name', type: 'text', required: true },
+            { name: 'score', type: 'number' },
+          ],
+        },
+        seed: [
+          {
+            id: 'player-1',
+            name: 'Ada',
+            score: 42,
+          },
+        ],
+      },
+      endpoints: [
+        ...crudEndpoints,
+        {
+          id: 'players.leaderboard',
+          method: 'GET',
+          path: '/leaderboard',
+          intent: 'custom',
+        },
+      ],
+    };
+    const manifest: AppApiManifest = {
+      apis: {
+        players: generatedApi,
+      },
+    };
+
+    expect(JSON.parse(JSON.stringify(manifest))).toEqual({
+      apis: {
+        players: generatedApi,
+      },
+    });
+    expect(manifest.apis?.players?.endpoints.map((endpoint) => endpoint.path)).toEqual([
+      '/',
+      '/',
+      '/{id}',
+      '/{id}',
+      '/{id}',
+      '/leaderboard',
+    ]);
+  });
+
+  test('serializes external APIs without generated resource definitions', () => {
+    const externalApi: AppApiDefinition = {
+      id: 'stripe',
+      kind: 'external',
+      label: 'Stripe',
+      basePath: '/api/stripe',
+      baseUrl: 'https://api.stripe.com',
+      endpoints: [
+        {
+          id: 'stripe.createCheckoutSession',
+          method: 'POST',
+          path: '/checkout/sessions',
+          intent: 'custom',
+          auth: {
+            required: true,
+            permissions: ['payments:create'],
+          },
+        },
+      ],
+    };
+
+    expect(JSON.parse(JSON.stringify(externalApi))).toEqual(externalApi);
+  });
+});

package/src/data/apis.ts

@@ -0,0 +1,105 @@
+import type { DbCollectionDefinition } from '../db';
+import type { DataOperationRequest, DataOperationResponse } from './operations';
+import type { DataContractValue } from './values';
+
+export const APP_API_KINDS = ['external', 'generated'] as const;
+export type AppApiKind = (typeof APP_API_KINDS)[number];
+
+export const APP_API_GENERATED_PRESETS = ['crud'] as const;
+export type AppApiGeneratedPreset = (typeof APP_API_GENERATED_PRESETS)[number];
+
+export const APP_API_ENDPOINT_METHODS = [
+  'DELETE',
+  'GET',
+  'HEAD',
+  'OPTIONS',
+  'PATCH',
+  'POST',
+  'PUT',
+] as const;
+export type AppApiEndpointMethod = (typeof APP_API_ENDPOINT_METHODS)[number];
+
+export const APP_API_ENDPOINT_INTENTS = [
+  'create',
+  'custom',
+  'delete',
+  'list',
+  'read',
+  'update',
+] as const;
+export type AppApiEndpointIntent = (typeof APP_API_ENDPOINT_INTENTS)[number];
+
+export type AppApiId = string;
+export type AppApiEndpointId = string;
+export type AppApiSeedRecord = Readonly<Record<string, DataContractValue>>;
+
+export interface AppApiAuthRequirement {
+  readonly required?: boolean;
+  readonly roles?: readonly string[];
+  readonly permissions?: readonly string[];
+  readonly policy?: string;
+  readonly metadata?: DataContractValue;
+}
+
+export interface AppApiCollectionResourceDefinition {
+  readonly kind: 'collection';
+  readonly collection: DbCollectionDefinition;
+  readonly seed?: readonly AppApiSeedRecord[];
+  readonly metadata?: DataContractValue;
+}
+
+export type AppApiResourceDefinition = AppApiCollectionResourceDefinition;
+
+export interface AppApiEndpointDefinition {
+  readonly id: AppApiEndpointId;
+  readonly label?: string;
+  readonly description?: string;
+  readonly method: AppApiEndpointMethod;
+  /**
+   * Path relative to the API base path. Use `/` for the base collection endpoint.
+   */
+  readonly path: string;
+  readonly intent?: AppApiEndpointIntent;
+  readonly request?: DataOperationRequest;
+  readonly response?: DataOperationResponse;
+  readonly auth?: AppApiAuthRequirement;
+  readonly metadata?: DataContractValue;
+}
+
+interface AppApiDefinitionBase {
+  readonly id: AppApiId;
+  readonly kind: AppApiKind;
+  readonly label?: string;
+  readonly description?: string;
+  readonly basePath: string;
+  readonly endpoints: readonly AppApiEndpointDefinition[];
+  readonly auth?: AppApiAuthRequirement;
+  readonly metadata?: DataContractValue;
+}
+
+export interface AppGeneratedApiDefinition extends AppApiDefinitionBase {
+  readonly kind: 'generated';
+  /**
+   * Preset used by authoring tools to seed standard endpoints. The resulting
+   * serialized API still stores concrete `endpoints[]` so custom endpoints can
+   * live next to generated CRUD operations.
+   */
+  readonly preset?: AppApiGeneratedPreset;
+  readonly resource?: AppApiResourceDefinition;
+}
+
+export interface AppExternalApiDefinition extends AppApiDefinitionBase {
+  readonly kind: 'external';
+  readonly baseUrl?: string;
+  readonly openApiUrl?: string;
+}
+
+export type AppApiDefinition = AppExternalApiDefinition | AppGeneratedApiDefinition;
+
+export type AppApiRegistry = Readonly<Record<AppApiId, AppApiDefinition>>;
+
+export interface AppDataManifest {
+  readonly apis?: AppApiRegistry;
+}
+
+export type AppApiManifest = AppDataManifest;

package/src/data/index.ts

@@ -1,4 +1,4 @@
-export * from './datasets';
+export * from './apis';
 export * from './diagnostics';
 export * from './endpoints';
 export * from './ids';

package/dist/data/datasets.d.ts

@@ -1,20 +0,0 @@
-import type { DbCollectionDefinition } from '../db';
-import type { DataContractValue } from './values';
-export declare const APP_DATASET_OPERATIONS: readonly ["create", "delete", "list", "read", "update"];
-export type AppDatasetOperation = (typeof APP_DATASET_OPERATIONS)[number];
-export type AppDatasetId = string;
-export type AppDatasetSeedRecord = Readonly<Record<string, DataContractValue>>;
-export interface AppDatasetDefinition {
-    readonly id: AppDatasetId;
-    readonly label?: string;
-    readonly description?: string;
-    readonly collection: DbCollectionDefinition;
-    readonly operations?: readonly AppDatasetOperation[];
-    readonly seed?: readonly AppDatasetSeedRecord[];
-    readonly metadata?: DataContractValue;
-}
-export type AppDatasetRegistry = Readonly<Record<AppDatasetId, AppDatasetDefinition>>;
-export interface AppDataManifest {
-    readonly datasets?: AppDatasetRegistry;
-}
-//# sourceMappingURL=datasets.d.ts.map

package/dist/data/datasets.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"datasets.d.ts","sourceRoot":"","sources":["../../src/data/datasets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,OAAO,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAElD,eAAO,MAAM,sBAAsB,yDAA0D,CAAC;AAC9F,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAClC,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC;AAE/E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,sBAAsB,CAAC;IAC5C,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACrD,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CACvC;AAED,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,oBAAoB,CAAC,CAAC,CAAC;AAEtF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CACxC"}

package/dist/data/datasets.js

@@ -1,2 +0,0 @@
-export const APP_DATASET_OPERATIONS = ['create', 'delete', 'list', 'read', 'update'];
-//# sourceMappingURL=datasets.js.map

package/dist/data/datasets.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"datasets.js","sourceRoot":"","sources":["../../src/data/datasets.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAU,CAAC","sourcesContent":["import type { DbCollectionDefinition } from '../db';\nimport type { DataContractValue } from './values';\n\nexport const APP_DATASET_OPERATIONS = ['create', 'delete', 'list', 'read', 'update'] as const;\nexport type AppDatasetOperation = (typeof APP_DATASET_OPERATIONS)[number];\n\nexport type AppDatasetId = string;\nexport type AppDatasetSeedRecord = Readonly<Record<string, DataContractValue>>;\n\nexport interface AppDatasetDefinition {\n  readonly id: AppDatasetId;\n  readonly label?: string;\n  readonly description?: string;\n  readonly collection: DbCollectionDefinition;\n  readonly operations?: readonly AppDatasetOperation[];\n  readonly seed?: readonly AppDatasetSeedRecord[];\n  readonly metadata?: DataContractValue;\n}\n\nexport type AppDatasetRegistry = Readonly<Record<AppDatasetId, AppDatasetDefinition>>;\n\nexport interface AppDataManifest {\n  readonly datasets?: AppDatasetRegistry;\n}\n"]}

package/src/data/datasets.ts

@@ -1,24 +0,0 @@
-import type { DbCollectionDefinition } from '../db';
-import type { DataContractValue } from './values';
-
-export const APP_DATASET_OPERATIONS = ['create', 'delete', 'list', 'read', 'update'] as const;
-export type AppDatasetOperation = (typeof APP_DATASET_OPERATIONS)[number];
-
-export type AppDatasetId = string;
-export type AppDatasetSeedRecord = Readonly<Record<string, DataContractValue>>;
-
-export interface AppDatasetDefinition {
-  readonly id: AppDatasetId;
-  readonly label?: string;
-  readonly description?: string;
-  readonly collection: DbCollectionDefinition;
-  readonly operations?: readonly AppDatasetOperation[];
-  readonly seed?: readonly AppDatasetSeedRecord[];
-  readonly metadata?: DataContractValue;
-}
-
-export type AppDatasetRegistry = Readonly<Record<AppDatasetId, AppDatasetDefinition>>;
-
-export interface AppDataManifest {
-  readonly datasets?: AppDatasetRegistry;
-}