@ontrails/store 0.2.0

package/src/adapter-support.ts

@@ -0,0 +1,178 @@
+import {
+  attachLateBoundSignalRef,
+  cloneSignalWithId,
+  signal,
+  ValidationError,
+} from '@ontrails/core';
+import type { Signal } from '@ontrails/core';
+import type { z } from 'zod';
+
+import type {
+  AnyStoreDefinition,
+  AnyStoreTable,
+  StoreTableSignals,
+} from './types.js';
+
+type MutableTables<TStore extends AnyStoreDefinition> = {
+  -readonly [TName in keyof TStore['tables']]: TStore['tables'][TName];
+};
+
+type StoreSignalChange = 'created' | 'removed' | 'updated';
+
+const storeSignalTokenCounter = Symbol.for(
+  '@ontrails/store.late-bound-signal-counter'
+);
+
+const takeStoreSignalTokenCounter = (): number => {
+  const globals = globalThis as Record<PropertyKey, unknown>;
+  const current = globals[storeSignalTokenCounter];
+  const next = typeof current === 'number' ? current : 0;
+  globals[storeSignalTokenCounter] = next + 1;
+  return next;
+};
+
+const createStoreSignalToken = (change: StoreSignalChange): string =>
+  `store-${change}-${takeStoreSignalTokenCounter()}`;
+
+const createStoreSignalDescription = (
+  tableName: string,
+  change: StoreSignalChange
+): string => {
+  switch (change) {
+    case 'created': {
+      return `Fired after a "${tableName}" entity is created.`;
+    }
+    case 'removed': {
+      return `Fired after a "${tableName}" entity is removed.`;
+    }
+    case 'updated': {
+      return `Fired after a "${tableName}" entity is updated.`;
+    }
+    default: {
+      throw new Error(`Unsupported store signal change: ${change as string}`);
+    }
+  }
+};
+
+const createStoreSignal = <TPayload>(
+  tableName: string,
+  change: StoreSignalChange,
+  payload: z.ZodType<TPayload>
+): Signal<TPayload> =>
+  attachLateBoundSignalRef(
+    signal(`${tableName}.${change}`, {
+      description: createStoreSignalDescription(tableName, change),
+      payload,
+    }),
+    {
+      kind: 'store-derived',
+      token: createStoreSignalToken(change),
+    }
+  );
+
+export const createStoreTableSignals = <TPayload>(
+  tableName: string,
+  payload: z.ZodType<TPayload>
+): StoreTableSignals<TPayload> =>
+  Object.freeze({
+    created: createStoreSignal(tableName, 'created', payload),
+    removed: createStoreSignal(tableName, 'removed', payload),
+    updated: createStoreSignal(tableName, 'updated', payload),
+  });
+
+export const composeStoreSignalId = (
+  scope: string,
+  tableName: string,
+  change: StoreSignalChange
+): string => `${scope}:${tableName}.${change}`;
+
+const bindTableSignals = (
+  scope: string,
+  table: AnyStoreTable
+): StoreTableSignals<unknown> =>
+  Object.freeze({
+    created: cloneSignalWithId(
+      table.signals.created,
+      composeStoreSignalId(scope, table.name, 'created')
+    ),
+    removed: cloneSignalWithId(
+      table.signals.removed,
+      composeStoreSignalId(scope, table.name, 'removed')
+    ),
+    updated: cloneSignalWithId(
+      table.signals.updated,
+      composeStoreSignalId(scope, table.name, 'updated')
+    ),
+  });
+
+const collectStoreSignals = <TStore extends AnyStoreDefinition>(
+  normalized: MutableTables<TStore>,
+  tableNames: readonly Extract<keyof TStore['tables'], string>[]
+) =>
+  Object.freeze(
+    tableNames.flatMap((name) => {
+      const table = normalized[name];
+      return table === undefined
+        ? []
+        : [table.signals.created, table.signals.updated, table.signals.removed];
+    })
+  );
+
+/**
+ * Verifies that a resource id is safe to compose into a scoped signal id.
+ *
+ * Scoped signal ids are matched by the `SCOPED_SIGNAL_ID` pattern in
+ * `@ontrails/core` (`^[^:\s]+:[^:.\s]+(?:\.[^:.\s]+)+$`). A resource id used
+ * as the scope segment must therefore be a non-empty string that contains
+ * neither `":"` nor any whitespace.
+ */
+export const isValidResourceId = (resourceId: string): boolean =>
+  resourceId.length > 0 && !resourceId.includes(':') && !/\s/.test(resourceId);
+
+const assertValidScope = (scope: string): void => {
+  if (!isValidResourceId(scope)) {
+    throw new ValidationError(
+      `Store resource id "${scope}" is invalid: must be a non-empty string with no ":" characters and no whitespace.`
+    );
+  }
+};
+
+export const bindStoreDefinition = <TStore extends AnyStoreDefinition>(
+  definition: TStore,
+  scope: string
+): TStore => {
+  assertValidScope(scope);
+
+  const tableNames = definition.tableNames as readonly Extract<
+    keyof TStore['tables'],
+    string
+  >[];
+  const tables = {} as MutableTables<TStore>;
+
+  for (const tableName of tableNames) {
+    const table = definition.tables[tableName];
+    if (table === undefined) {
+      continue;
+    }
+
+    tables[tableName] = Object.freeze({
+      ...table,
+      signals: bindTableSignals(scope, table),
+    }) as MutableTables<TStore>[typeof tableName];
+  }
+
+  const get =
+    'get' in definition && typeof definition.get === 'function'
+      ? <TName extends Extract<keyof TStore['tables'], string>>(name: TName) =>
+          tables[name]
+      : undefined;
+
+  return Object.freeze({
+    ...definition,
+    ...(get ? { get } : {}),
+    signals: collectStoreSignals(tables, tableNames),
+    tables: Object.freeze(tables),
+  }) as TStore;
+};
+
+export type { StoreSignalChange };

package/src/crud-doctrine.ts

@@ -0,0 +1,43 @@
+export const crudOperations = [
+  'create',
+  'read',
+  'update',
+  'delete',
+  'list',
+] as const;
+
+export type CrudOperation = (typeof crudOperations)[number];
+
+export interface CrudAccessorExpectation {
+  readonly fallback?: string | undefined;
+  readonly preferred: string;
+  readonly severityWhenNoFallback: 'error';
+  readonly severityWhenPreferredMissingWithFallback?: 'warn' | undefined;
+}
+
+export const crudAccessorExpectations = {
+  create: {
+    fallback: 'upsert',
+    preferred: 'insert',
+    severityWhenNoFallback: 'error',
+    severityWhenPreferredMissingWithFallback: 'warn',
+  },
+  delete: {
+    preferred: 'remove',
+    severityWhenNoFallback: 'error',
+  },
+  list: {
+    preferred: 'list',
+    severityWhenNoFallback: 'error',
+  },
+  read: {
+    preferred: 'get',
+    severityWhenNoFallback: 'error',
+  },
+  update: {
+    fallback: 'upsert',
+    preferred: 'update',
+    severityWhenNoFallback: 'error',
+    severityWhenPreferredMissingWithFallback: 'warn',
+  },
+} as const satisfies Record<CrudOperation, CrudAccessorExpectation>;

package/src/index.ts

@@ -0,0 +1,48 @@
+export { crudAccessorExpectations, crudOperations } from './crud-doctrine.js';
+export type {
+  CrudAccessorExpectation,
+  CrudOperation,
+} from './crud-doctrine.js';
+export { store, versionFieldName } from './store.js';
+export type {
+  AnyStoreDefinition,
+  AnyStoreTable,
+  EntityOf,
+  FiltersOf,
+  FixtureInputOf,
+  FixtureOf,
+  FixturesOfInput,
+  GeneratedFieldsOfInput,
+  GeneratedKeysOf,
+  IdentityFieldOfInput,
+  IdentityOf,
+  IndexFieldsOfInput,
+  IndexedFieldsOfInput,
+  InsertOf,
+  ReadOnlyStoreConnection,
+  StoreAccessor,
+  ReadOnlyStoreTableAccessor,
+  ReferencesOfInput,
+  StoreAccessMode,
+  StoreConnection,
+  StoreAdapterOptions,
+  StoreDefinition,
+  StoreFieldKey,
+  StoreFixtureInput,
+  StoreFixtureRow,
+  StoreIdentifierOf,
+  StoreKind,
+  StoreListOptions,
+  StoreMockSeed,
+  StoreObjectSchema,
+  StoreOptions,
+  StoreSearchDefinition,
+  StoreTable,
+  StoreTableSignals,
+  StoreTableAccessor,
+  StoreTableConnection,
+  StoreTableInput,
+  StoreTablesInput,
+  UpsertOf,
+  UpdateOf,
+} from './types.js';

package/src/jsonfile/index.ts

@@ -0,0 +1,6 @@
+export { connectJsonFile, jsonFile, jsonFile as store } from './runtime.js';
+export type {
+  JsonFileConnection,
+  JsonFileStoreOptions,
+  JsonFileStoreResource,
+} from './types.js';