@conduction/nextcloud-vue 0.1.0-beta.6 → 0.1.0-beta.8

package/src/store/createCrudStore.js

@@ -0,0 +1,360 @@
+import { defineStore } from 'pinia'
+import { buildHeaders, prefixUrl } from '../utils/headers.js'
+import { parseResponseError } from '../utils/errors.js'
+
+/**
+ * Default fields stripped from items before POST/PUT.
+ * @type {string[]}
+ */
+const DEFAULT_CLEAN_FIELDS = ['id', 'uuid', 'created', 'updated']
+
+/**
+ * Default base URL for the API.
+ * @type {string}
+ */
+const DEFAULT_BASE_URL = '/apps/openregister/api'
+
+/**
+ * Default list-response parser — extracts the `results` array.
+ *
+ * Called with the store as `this`, so custom implementations can
+ * perform side-effects (e.g. update extra state from the response).
+ *
+ * @param {object} json Parsed response body
+ * @return {Array} The items array for setList
+ */
+function defaultParseListResponse(json) {
+	return json.results
+}
+
+/**
+ * Create a Pinia store with standard CRUD operations.
+ *
+ * Generates a store with list/item state, pagination, filters, and
+ * async actions for fetching, creating, updating, and deleting items.
+ * Domain-specific state, getters, and actions can be added via `extend`.
+ *
+ * @example
+ * // Minimal — pure CRUD
+ * import { createCrudStore } from '@conduction/nextcloud-vue'
+ * import { Source } from '../../entities/index.js'
+ *
+ * export const useSourceStore = createCrudStore('source', {
+ *   endpoint: 'sources',
+ *   entity: Source,
+ * })
+ *
+ * @example
+ * // With features and extensions
+ * import { createCrudStore } from '@conduction/nextcloud-vue'
+ * import { Agent } from '../../entities/index.js'
+ *
+ * export const useAgentStore = createCrudStore('agent', {
+ *   endpoint: 'agents',
+ *   entity: Agent,
+ *   features: { loading: true, viewMode: true },
+ *   extend: {
+ *     actions: {
+ *       async getStats() {
+ *         const response = await fetch(this._options.baseApiUrl + '/stats')
+ *         if (!response.ok) throw new Error('HTTP ' + response.status)
+ *         return response.json()
+ *       },
+ *     },
+ *   },
+ * })
+ *
+ * @param {string} name Pinia store ID (e.g. 'source', 'agent')
+ * @param {object} config Store configuration
+ * @param {string} config.endpoint API resource path segment (e.g. 'sources')
+ * @param {string} [config.baseUrl] API base URL (before endpoint)
+ * @param {Function|null} [config.entity] Entity class constructor for wrapping items, or null for raw data
+ * @param {string[]} [config.cleanFields] Fields to strip in cleanForSave
+ * @param {object} [config.features] Feature flags to enable optional state/getters/actions
+ * @param {boolean} [config.features.loading] Add loading/error state and isLoading/getError getters
+ * @param {boolean} [config.features.viewMode] Add viewMode state, getViewMode getter, setViewMode action
+ * @param {Function} [config.parseListResponse] Custom response parser for refreshList.
+ *   Receives the parsed JSON body with the store instance as `this`.
+ *   Must return an array of items. Default: `(json) => json.results`
+ * @param {object} [config.extend] Extra state/getters/actions to merge into the store
+ * @param {Function} [config.extend.state] State factory returning extra state properties
+ * @param {object} [config.extend.getters] Extra getters (or overrides of base getters)
+ * @param {object} [config.extend.actions] Extra actions (or overrides of base actions)
+ * @return {Function} Pinia store composable (useXxxStore)
+ */
+export function createCrudStore(name, config = {}) {
+	const {
+		endpoint,
+		baseUrl = DEFAULT_BASE_URL,
+		entity: Entity = null,
+		cleanFields = DEFAULT_CLEAN_FIELDS,
+		features = {},
+		parseListResponse = defaultParseListResponse,
+		extend = {},
+	} = config
+
+	if (!endpoint) {
+		throw new Error(`createCrudStore("${name}"): config.endpoint is required`)
+	}
+
+	const baseApiUrl = prefixUrl(`${baseUrl}/${endpoint}`)
+
+	return defineStore(name, {
+		state: () => ({
+			// ── Core state ──
+			item: null,
+			list: [],
+			filters: {},
+			pagination: { page: 1, limit: 20 },
+
+			// ── Optional feature state ──
+			...(features.loading ? { loading: false, error: null } : {}),
+			...(features.viewMode ? { viewMode: 'cards' } : {}),
+
+			// ── Internal config (available to extend actions) ──
+			_options: { endpoint, cleanFields, baseApiUrl },
+
+			// ── Domain-specific state ──
+			...(typeof extend.state === 'function' ? extend.state() : {}),
+		}),
+
+		getters: {
+			// ── Optional feature getters ──
+			...(features.viewMode ? { getViewMode: (state) => state.viewMode } : {}),
+			...(features.loading
+				? {
+					isLoading: (state) => state.loading,
+					getError: (state) => state.error,
+				}
+				: {}),
+
+			// ── Domain-specific getters ──
+			...(extend.getters ?? {}),
+		},
+
+		actions: {
+			// ── Setters ──
+
+			/**
+			 * Set the active item. Wraps in Entity class if configured.
+			 * @param {object|null} data Raw item data or null to clear
+			 */
+			setItem(data) {
+				this.item = data
+					? (Entity ? new Entity(data) : data)
+					: null
+			},
+
+			/**
+			 * Set the item list. Wraps each item in Entity class if configured.
+			 * @param {Array} data Array of raw item objects
+			 */
+			setList(data) {
+				this.list = Entity
+					? data.map((item) => new Entity(item))
+					: [...data]
+			},
+
+			/**
+			 * Set pagination parameters.
+			 * @param {number} page Current page number
+			 * @param {number} [limit] Items per page
+			 */
+			setPagination(page, limit = 20) {
+				this.pagination = { page, limit }
+			},
+
+			/**
+			 * Merge filter criteria into the current filters.
+			 * @param {object} filters Key-value filter pairs to merge
+			 */
+			setFilters(filters) {
+				this.filters = { ...this.filters, ...filters }
+			},
+
+			// ── Optional feature actions ──
+			...(features.viewMode
+				? {
+					/**
+					 * Set the view mode (e.g. 'cards', 'table').
+					 * @param {string} mode View mode identifier
+					 */
+					setViewMode(mode) {
+						this.viewMode = mode
+					},
+				}
+				: {}),
+
+			// ── CRUD actions ──
+
+			/**
+			 * Fetch the item list from the API.
+			 * @param {string|null} [search] Optional search query
+			 * @param {boolean} [soft] If true, don't toggle loading state
+			 * @return {Promise<{response: Response, data: Array}>}
+			 */
+			async refreshList(search = null, soft = false) {
+				if (features.loading && !soft) {
+					this.loading = true
+					this.error = null
+				}
+				try {
+					let url = this._options.baseApiUrl
+					if (search) {
+						url += '?_search=' + encodeURIComponent(search)
+					}
+					const response = await fetch(url, {
+						method: 'GET',
+						headers: buildHeaders(),
+					})
+					if (!response.ok) {
+						throw await parseResponseError(response, name)
+					}
+					const json = await response.json()
+					const data = parseListResponse.call(this, json)
+					this.setList(data)
+					return { response, data }
+				} catch (error) {
+					if (features.loading) {
+						this.error = error.message ?? error.toString()
+					}
+					throw error
+				} finally {
+					if (features.loading && !soft) {
+						this.loading = false
+					}
+				}
+			},
+
+			/**
+			 * Fetch a single item by ID and set it as the active item.
+			 * @param {string|number} id Item ID or UUID
+			 * @return {Promise<object>} The fetched item data
+			 */
+			async getOne(id) {
+				if (features.loading) {
+					this.loading = true
+				}
+				try {
+					const response = await fetch(`${this._options.baseApiUrl}/${id}`, {
+						method: 'GET',
+						headers: buildHeaders(),
+					})
+					if (!response.ok) {
+						throw await parseResponseError(response, name)
+					}
+					const data = await response.json()
+					this.setItem(data)
+					return data
+				} catch (error) {
+					if (features.loading) {
+						this.error = error.message ?? error.toString()
+					}
+					throw error
+				} finally {
+					if (features.loading) {
+						this.loading = false
+					}
+				}
+			},
+
+			/**
+			 * Delete an item by ID. Refreshes the list and clears the active item.
+			 * @param {object} item Item object (must have .id)
+			 * @return {Promise<{response: Response}>}
+			 */
+			async deleteOne(item) {
+				if (!item.id) {
+					throw new Error(`No ${name} to delete`)
+				}
+				if (features.loading) {
+					this.loading = true
+				}
+				try {
+					const response = await fetch(`${this._options.baseApiUrl}/${item.id}`, {
+						method: 'DELETE',
+						headers: buildHeaders(),
+					})
+					if (!response.ok) {
+						throw await parseResponseError(response, name)
+					}
+					await this.refreshList()
+					this.setItem(null)
+					return { response }
+				} catch (error) {
+					if (features.loading) {
+						this.error = error.message ?? error.toString()
+					}
+					throw error
+				} finally {
+					if (features.loading) {
+						this.loading = false
+					}
+				}
+			},
+
+			/**
+			 * Strip read-only fields from an item before saving.
+			 * Uses the `cleanFields` config array. Override in `extend.actions`
+			 * for custom cleaning (the configured fields are in `this._options.cleanFields`).
+			 * @param {object} item Raw item data
+			 * @return {object} Cleaned copy safe for POST/PUT
+			 */
+			cleanForSave(item) {
+				const cleaned = { ...item }
+				for (const field of this._options.cleanFields) {
+					delete cleaned[field]
+				}
+				return cleaned
+			},
+
+			/**
+			 * Create or update an item. Determines method from presence of `.id`.
+			 * @param {object} item Item data (without .id = create, with .id = update)
+			 * @return {Promise<{response: Response, data: object}>}
+			 */
+			async save(item) {
+				if (!item) {
+					throw new Error(`No ${name} to save`)
+				}
+				if (features.loading) {
+					this.loading = true
+				}
+				const isNew = !item.id
+				const url = isNew
+					? this._options.baseApiUrl
+					: `${this._options.baseApiUrl}/${item.id}`
+				const method = isNew ? 'POST' : 'PUT'
+				const body = this.cleanForSave(item)
+
+				try {
+					const response = await fetch(url, {
+						method,
+						headers: buildHeaders(),
+						body: JSON.stringify(body),
+					})
+					if (!response.ok) {
+						throw await parseResponseError(response, name)
+					}
+					const responseData = await response.json()
+					const data = Entity ? new Entity(responseData) : responseData
+					this.setItem(data)
+					await this.refreshList()
+					return { response, data }
+				} catch (error) {
+					if (features.loading) {
+						this.error = error.message ?? error.toString()
+					}
+					throw error
+				} finally {
+					if (features.loading) {
+						this.loading = false
+					}
+				}
+			},
+
+			// ── Domain-specific actions (may override base actions) ──
+			...(extend.actions ?? {}),
+		},
+	})
+}

package/src/store/createSubResourcePlugin.js

@@ -1,26 +1,16 @@
-import { buildHeaders, buildQueryString } from '../utils/headers.js'
+import { buildHeaders, buildQueryString, capitalize } from '../utils/headers.js'
 import { parseResponseError, networkError } from '../utils/errors.js'
 
 /**
  * Standard empty paginated response shape used by all sub-resource plugins.
  *
- * @param {number} [limit=20] Default page size
+ * @param {number} [limit] Default page size
  * @return {object} Empty paginated state
  */
 export function emptyPaginated(limit = 20) {
 	return { results: [], total: 0, page: 1, pages: 0, limit, offset: 0 }
 }
 
-/**
- * Capitalize the first letter of a string.
- *
- * @param {string} str Input string
- * @return {string} Capitalized string
- */
-function capitalize(str) {
-	return str.charAt(0).toUpperCase() + str.slice(1)
-}
-
 /**
  * Create a sub-resource plugin for the object store.
  *
@@ -30,8 +20,8 @@ function capitalize(str) {
  *
  * @param {string} name Camel-case name for the sub-resource (e.g. 'auditTrails')
  * @param {string} endpoint URL path segment appended to the object URL (e.g. 'audit-trails')
- * @param {object} [options={}] Plugin options
- * @param {number} [options.limit=20] Default page size
+ * @param {object} [options] Plugin options
+ * @param {number} [options.limit] Default page size
  * @return {Function} Plugin factory that returns the plugin definition
  *
  * @example
@@ -76,7 +66,7 @@ export function createSubResourcePlugin(name, endpoint, options = {}) {
 			 *
 			 * @param {string} type The registered object type slug
 			 * @param {string} objectId The parent object ID
-			 * @param {object} [params={}] Query parameters (_search, _limit, _page)
+			 * @param {object} [params] Query parameters (_search, _limit, _page)
 			 * @return {Promise<Array>} The fetched results
 			 */
 			async [`fetch${cap}`](type, objectId, params = {}) {

package/src/store/index.js

@@ -1,3 +1,4 @@
 export { useObjectStore, createObjectStore } from './useObjectStore.js'
+export { createCrudStore } from './createCrudStore.js'
 export { createSubResourcePlugin, emptyPaginated } from './createSubResourcePlugin.js'
 export { auditTrailsPlugin, relationsPlugin, filesPlugin, lifecyclePlugin, selectionPlugin, searchPlugin, SEARCH_TYPE, getRegisterApiUrl, getSchemaApiUrl } from './plugins/index.js'