@dotdo/do 0.1.0

package/dist/db/collections/verbs.d.ts

@@ -0,0 +1,308 @@
+/**
+ * Verb Collection - Action type registry for Digital Objects
+ *
+ * @module collections/verbs
+ *
+ * @description
+ * Manages the registration and lookup of Verbs (action types) within a Digital Object.
+ * Verbs define the grammatical forms and semantics of actions following the
+ * linguistic pattern from digital-objects.
+ *
+ * Every verb has multiple forms:
+ * - action: Imperative form (create, update, delete)
+ * - act: Short form for compact references
+ * - activity: Present participle (creating, updating, deleting)
+ * - event: Past tense for events (created, updated, deleted)
+ * - reverse: Passive form (createdBy, updatedBy, deletedBy)
+ * - inverse: Opposite action (create <-> delete, start <-> stop)
+ *
+ * @example
+ * ```typescript
+ * const verbs = new VerbCollection(storage)
+ *
+ * // Register standard CRUD verbs
+ * await verbs.registerCrudVerbs()
+ *
+ * // Register custom verb
+ * await verbs.create({
+ *   name: 'Subscribe',
+ *   action: 'subscribe',
+ *   act: 'sub',
+ *   activity: 'subscribing',
+ *   event: 'subscribed',
+ *   reverse: 'subscribedBy',
+ *   inverse: 'unsubscribe'
+ * })
+ * ```
+ */
+import type { Verb } from '../../types/collections';
+import { BaseCollection, DOStorage } from './base';
+/**
+ * Options for creating a verb
+ */
+export interface CreateVerbOptions {
+    /**
+     * Verb name (display name)
+     */
+    name: string;
+    /**
+     * Imperative form
+     * @example 'create', 'subscribe', 'approve'
+     */
+    action: string;
+    /**
+     * Short form for compact references
+     * @example 'new', 'sub', 'ok'
+     */
+    act: string;
+    /**
+     * Present participle form
+     * @example 'creating', 'subscribing', 'approving'
+     */
+    activity: string;
+    /**
+     * Past tense / event form
+     * @example 'created', 'subscribed', 'approved'
+     */
+    event: string;
+    /**
+     * Passive / reverse form
+     * @example 'createdBy', 'subscribedBy', 'approvedBy'
+     */
+    reverse: string;
+    /**
+     * Opposite action (optional)
+     * @example 'delete' for 'create', 'unsubscribe' for 'subscribe'
+     */
+    inverse?: string;
+    /**
+     * Human-readable description
+     */
+    description?: string;
+}
+/**
+ * Standard CRUD verb definitions
+ */
+export declare const CRUD_VERBS: CreateVerbOptions[];
+/**
+ * Common workflow verb definitions
+ */
+export declare const WORKFLOW_VERBS: CreateVerbOptions[];
+/**
+ * Verb collection for managing action type definitions
+ *
+ * @description
+ * The VerbCollection provides methods for registering, looking up, and managing
+ * action types. Each verb defines grammatical forms that are used throughout
+ * the system for:
+ *
+ * - Actions: Active operations (e.g., "create customer")
+ * - Events: What happened (e.g., "customer.created")
+ * - Relationships: Reverse relations (e.g., "createdBy user")
+ *
+ * @example
+ * ```typescript
+ * const verbs = new VerbCollection(storage)
+ *
+ * // Register CRUD verbs
+ * await verbs.registerCrudVerbs()
+ *
+ * // Look up by action
+ * const createVerb = await verbs.getByAction('create')
+ * console.log(createVerb.event) // 'created'
+ *
+ * // Get event name for a verb
+ * const eventName = await verbs.getEventForm('subscribe')
+ * console.log(eventName) // 'subscribed'
+ * ```
+ */
+export declare class VerbCollection extends BaseCollection<Verb> {
+    /**
+     * Create a new VerbCollection instance
+     *
+     * @param storage - DO storage interface
+     */
+    constructor(storage: DOStorage);
+    /**
+     * Initialize the verbs table in SQLite
+     *
+     * @internal
+     */
+    protected initializeTable(): Promise<void>;
+    /**
+     * Create a new verb
+     *
+     * @param data - Verb creation options
+     * @returns The created verb with generated ID
+     *
+     * @throws {ValidationError} If action form already exists
+     *
+     * @example
+     * ```typescript
+     * const verb = await verbs.create({
+     *   name: 'Publish',
+     *   action: 'publish',
+     *   act: 'pub',
+     *   activity: 'publishing',
+     *   event: 'published',
+     *   reverse: 'publishedBy'
+     * })
+     * ```
+     */
+    create(data: Omit<Verb, 'id'>): Promise<Verb>;
+    /**
+     * Get a verb by its action form
+     *
+     * @param action - The verb's action form (imperative)
+     * @returns The verb or null if not found
+     *
+     * @example
+     * ```typescript
+     * const createVerb = await verbs.getByAction('create')
+     * ```
+     */
+    getByAction(action: string): Promise<Verb | null>;
+    /**
+     * Get a verb by its event form
+     *
+     * @param event - The verb's event form (past tense)
+     * @returns The verb or null if not found
+     *
+     * @example
+     * ```typescript
+     * const verb = await verbs.getByEvent('created')
+     * console.log(verb.action) // 'create'
+     * ```
+     */
+    getByEvent(event: string): Promise<Verb | null>;
+    /**
+     * Get a verb by any of its forms
+     *
+     * @param form - Any verb form (action, act, activity, event, reverse)
+     * @returns The verb or null if not found
+     *
+     * @example
+     * ```typescript
+     * const verb = await verbs.getByAnyForm('creating')
+     * console.log(verb.action) // 'create'
+     * ```
+     */
+    getByAnyForm(form: string): Promise<Verb | null>;
+    /**
+     * Get the event form for an action
+     *
+     * @param action - Action form of the verb
+     * @returns Event form or null if verb not found
+     *
+     * @example
+     * ```typescript
+     * const event = await verbs.getEventForm('subscribe')
+     * console.log(event) // 'subscribed'
+     * ```
+     */
+    getEventForm(action: string): Promise<string | null>;
+    /**
+     * Get the reverse form for an action
+     *
+     * @param action - Action form of the verb
+     * @returns Reverse form or null if verb not found
+     *
+     * @example
+     * ```typescript
+     * const reverse = await verbs.getReverseForm('create')
+     * console.log(reverse) // 'createdBy'
+     * ```
+     */
+    getReverseForm(action: string): Promise<string | null>;
+    /**
+     * Get the inverse verb for an action
+     *
+     * @param action - Action form of the verb
+     * @returns Inverse verb or null if not defined
+     *
+     * @example
+     * ```typescript
+     * const inverse = await verbs.getInverse('create')
+     * console.log(inverse?.action) // 'delete'
+     * ```
+     */
+    getInverse(action: string): Promise<Verb | null>;
+    /**
+     * Register standard CRUD verbs
+     *
+     * @returns Array of created verbs
+     *
+     * @description
+     * Registers: create, read, update, delete
+     *
+     * @example
+     * ```typescript
+     * await verbs.registerCrudVerbs()
+     * ```
+     */
+    registerCrudVerbs(): Promise<Verb[]>;
+    /**
+     * Register common workflow verbs
+     *
+     * @returns Array of created verbs
+     *
+     * @description
+     * Registers: start, stop, approve, reject, submit, complete, cancel
+     *
+     * @example
+     * ```typescript
+     * await verbs.registerWorkflowVerbs()
+     * ```
+     */
+    registerWorkflowVerbs(): Promise<Verb[]>;
+    /**
+     * Validate verb action format
+     *
+     * @param action - Action to validate
+     * @returns True if valid
+     *
+     * @description
+     * Valid actions:
+     * - Lowercase alphabetic characters only
+     * - 2-32 characters
+     *
+     * @example
+     * ```typescript
+     * verbs.validateAction('create')   // true
+     * verbs.validateAction('Create')   // false (uppercase)
+     * verbs.validateAction('create1')  // false (number)
+     * ```
+     */
+    validateAction(action: string): boolean;
+    /**
+     * Generate verb forms from base action
+     *
+     * @param action - Base action form
+     * @returns Generated verb forms (best effort)
+     *
+     * @description
+     * Attempts to generate grammatical forms automatically.
+     * Results should be reviewed for irregular verbs.
+     *
+     * @example
+     * ```typescript
+     * const forms = verbs.generateForms('process')
+     * // { action: 'process', activity: 'processing', event: 'processed', reverse: 'processedBy' }
+     * ```
+     */
+    generateForms(action: string): Partial<CreateVerbOptions>;
+    /**
+     * Export all verbs as a lookup map
+     *
+     * @returns Map of action to full verb definition
+     *
+     * @example
+     * ```typescript
+     * const lookup = await verbs.exportLookup()
+     * // { create: { ... }, update: { ... }, ... }
+     * ```
+     */
+    exportLookup(): Promise<Record<string, Verb>>;
+}
+export default VerbCollection;
+//# sourceMappingURL=verbs.d.ts.map

package/dist/db/collections/verbs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verbs.d.ts","sourceRoot":"","sources":["../../../db/collections/verbs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAA;AACnD,OAAO,EAAE,cAAc,EAAE,SAAS,EAAkC,MAAM,QAAQ,CAAA;AAElF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IAEZ;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAA;IAEX;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;IAEhB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IAEb;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IAEf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE,iBAAiB,EAuCzC,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,iBAAiB,EAoE7C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,cAAe,SAAQ,cAAc,CAAC,IAAI,CAAC;IACtD;;;;OAIG;gBACS,OAAO,EAAE,SAAS;IAO9B;;;;OAIG;cACa,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBhD;;;;;;;;;;;;;;;;;;;OAmBG;IACG,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IASnD;;;;;;;;;;OAUG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAKvD;;;;;;;;;;;OAWG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAKrD;;;;;;;;;;;OAWG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAKtD;;;;;;;;;;;OAWG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAK1D;;;;;;;;;;;OAWG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAK5D;;;;;;;;;;;OAWG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAMtD;;;;;;;;;;;;OAYG;IACG,iBAAiB,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;IAW1C;;;;;;;;;;;;OAYG;IACG,qBAAqB,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;IAW9C;;;;;;;;;;;;;;;;;OAiBG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAKvC;;;;;;;;;;;;;;;OAeG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA4CzD;;;;;;;;;;OAUG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;CAIpD;AAED,eAAe,cAAc,CAAA"}