json-rest-api 1.0.7 → 1.0.8

package/plugins/core/rest-api-plugin-methods/put.js

@@ -0,0 +1,257 @@
+import { RestApiResourceError } from '../../../lib/rest-api-errors.js';
+import { validatePutPayload } from '../lib/querying-writing/payload-validators.js';
+import { processRelationships } from '../lib/writing/relationship-processor.js';
+import { updateManyToManyRelationship, createPivotRecords } from '../lib/writing/many-to-many-manipulations.js';
+import { ERROR_SUBTYPES } from '../lib/querying-writing/knex-constants.js';
+import { 
+  setupCommonRequest, 
+  validateResourceAttributesBeforeWrite,
+  validateRelationshipAccess,
+  applyFieldSetters,
+  validatePivotResource,
+  handleRecordReturnAfterWrite,
+  handleWriteMethodError
+} from './common.js';
+
+/**
+ * PUT
+ * Updates an existing top-level resource by completely replacing it.
+ * This method supports updating both attributes and relationships (1:1 and n:n).
+ * PUT is a complete replacement - any relationships not provided will be removed/nulled.
+ * This method does NOT support creating new related resources via an `included` array.
+ */
+export default async function putMethod({ 
+  params, 
+  context, 
+  vars, 
+  helpers, 
+  scope, 
+  scopes, 
+  runHooks, 
+  apiOptions, 
+  pluginOptions, 
+  scopeOptions, 
+  scopeName,
+  api,
+  log
+}) {
+  context.method = 'put';
+  
+  try {
+    const { schema, schemaStructure, schemaRelationships } = await setupCommonRequest({
+      params, 
+      context, 
+      vars, 
+      scopes, 
+      scopeOptions, 
+      scopeName,
+      api, 
+      helpers
+    });
+    context.id = context.inputRecord.data.id;
+    
+    // Run early hooks for pre-processing (e.g., file handling)
+    await runHooks('beforeProcessing');
+    await runHooks('beforeProcessingPut');
+
+    // Validate PUT payload to ensure it's a complete resource replacement operation.
+    // PUT requires the full resource representation including ID (unlike POST which generates ID).
+    // It validates that data.id matches the URL parameter, prevents 'included' array (which is
+    // read-only), and ensures the payload represents a complete replacement. Any fields not
+    // provided will be removed or reset to defaults - this is the key difference from PATCH.
+    // Example: PUT to /articles/123 must have data.id: '123' and all required fields.
+    validatePutPayload(context.inputRecord, scopes);
+    
+    // Validate that user has read access to all related resources
+    // This ensures users can only create relationships to resources they can access
+    await validateRelationshipAccess(context, context.inputRecord, helpers, runHooks, api);
+    
+    // Extract foreign keys from JSON:API relationships and prepare many-to-many operations
+    // Example: relationships.author -> author_id: '123' for storage
+    // Example: relationships.tags -> array of pivot records to create later
+    const { belongsToUpdates, manyToManyRelationships } = processRelationships(
+      scope,
+      { context }
+    );
+
+    await validateResourceAttributesBeforeWrite({ 
+      context, 
+      schema, 
+      belongsToUpdates, 
+      runHooks
+    });
+
+    // Check existence first
+    context.exists = await helpers.dataExists({
+      scopeName,
+      context
+    });
+  
+    context.isCreate = !context.exists;
+    context.isUpdate = context.exists;
+
+    // Fetch minimal record for authorization checks (only for updates)
+    if (context.isUpdate) {
+      const minimalRecord = await helpers.dataGetMinimal({
+        scopeName,
+        context,
+        runHooks
+      });
+
+      if (!minimalRecord) {
+        throw new RestApiResourceError(
+          `Resource not found: ${scopeName}/${context.id}`,
+          ERROR_SUBTYPES.NOT_FOUND
+        );
+      }
+
+      context.minimalRecord = minimalRecord;
+    }
+
+    // For PUT, we also need to handle relationships that are NOT provided
+    // (they should be set to null/empty as PUT is a complete replacement)
+    const allRelationships = {};
+    
+    // Collect all defined relationships for this resource
+    for (const [relName, relDef] of Object.entries(schemaRelationships || {})) {
+      if (relDef.manyToMany) {
+        allRelationships[relName] = { type: 'manyToMany', relDef: relDef.manyToMany };
+      }
+      // Also recognize hasMany with through as many-to-many
+      else if (relDef.hasMany && relDef.through) {
+        allRelationships[relName] = { 
+          type: 'manyToMany', 
+          relDef: {
+            through: relDef.through,
+            foreignKey: relDef.foreignKey,
+            otherKey: relDef.otherKey
+          }
+        };
+      }
+    }
+    
+    // Also check schema fields for belongsTo relationships
+    for (const [fieldName, fieldDef] of Object.entries(schemaStructure)) {
+      if (fieldDef.as && fieldDef.belongsTo) {
+        allRelationships[fieldDef.as] = { 
+          type: 'belongsTo',
+          fieldName,
+          fieldDef 
+        };
+      }
+    }
+    
+    // Process missing relationships (PUT should null them out only if relationships object exists)
+    const hasRelationshipsObject = context.inputRecord.data.relationships !== undefined;
+    const providedRelationships = new Set(Object.keys(context.inputRecord.data.relationships || {}));
+    
+    // Only null out missing relationships if a relationships object was provided
+    if (hasRelationshipsObject) {
+      for (const [relName, relInfo] of Object.entries(allRelationships)) {
+        if (!providedRelationships.has(relName)) {
+          if (relInfo.type === 'belongsTo') {
+            belongsToUpdates[relInfo.fieldName] = null;
+          } else if (relInfo.type === 'manyToMany') {
+            // Add to manyToManyRelationships with empty array
+            manyToManyRelationships.push({
+              relName,
+              relDef: relInfo.relDef,
+              relData: []  // Empty array means delete all
+            });
+          }
+        }
+      }
+    }
+
+    // Merge belongsTo updates with attributes
+    if (Object.keys(belongsToUpdates).length > 0) {
+      context.inputRecord.data.attributes = {
+        ...context.inputRecord.data.attributes,
+        ...belongsToUpdates
+      };
+    }
+
+    // Centralised checkPermissions function
+    await scope.checkPermissions({
+      method: 'put',
+      auth: context.auth,
+      id: context.id,
+      minimalRecord: context.minimalRecord,
+      isUpdate: context.isUpdate,
+      transaction: context.transaction
+    });
+  
+    await runHooks('beforeDataCall');
+    await runHooks('beforeDataCallPut');
+    
+    // Apply field setters after validation and before storage
+    if (context.inputRecord?.data?.attributes) {
+      context.inputRecord.data.attributes = await applyFieldSetters(
+        context.inputRecord.data.attributes,
+        context.schemaInfo,
+        context,
+        api,
+        helpers
+      );
+    }
+    
+    // Pass the operation type to the helper
+    await helpers.dataPut({
+      scopeName,
+      context
+    });
+    await runHooks('afterDataCallPut');
+    await runHooks('afterDataCall');
+
+    // Process many-to-many relationships after main record update/creation
+    for (const { relName, relDef, relData } of manyToManyRelationships) {
+      // Validate pivot resource exists
+      await validatePivotResource(scopes, relDef, relName);
+      
+      // Use smart sync for updates (like industry standard ORMs)
+      if (context.isUpdate) {
+        // Update many-to-many relationships using intelligent synchronization
+        // This preserves existing pivot data while efficiently updating relationships
+        await updateManyToManyRelationship(null, {
+          api,
+          context: {
+            resourceId: context.id,
+            relDef,
+            relData,
+            transaction: context.transaction
+          }
+        });
+      } else {
+        // For new records, just create the pivot records
+        if (relData.length > 0) {
+          await createPivotRecords(api, context.id, relDef, relData, context.transaction);
+        }
+      }
+    }
+   
+    const ret = await handleRecordReturnAfterWrite({
+      context,
+      scopeName,
+      api,
+      scopes,
+      schemaStructure,
+      schemaRelationships,
+      scopeOptions,
+      vars,
+      runHooks,
+      helpers,
+      log
+    });
+
+    // Commit transaction if we created it
+    if (context.shouldCommit) {
+      await context.transaction.commit();
+      await runHooks('afterCommit');
+    }
+
+    return ret;
+   
+  } catch (error) {
+    await handleWriteMethodError(error, context, 'PUT', scopeName, log, runHooks);
+  }
+}

package/plugins/core/rest-api-plugin-methods/query.js

@@ -0,0 +1,208 @@
+import { RestApiValidationError } from '../../../lib/rest-api-errors.js';
+import { validateQueryPayload } from '../lib/querying-writing/payload-validators.js';
+import { normalizeRecordAttributes } from '../lib/querying-writing/database-value-normalizers.js';
+import { getRequestedComputedFields } from '../lib/querying-writing/knex-field-helpers.js';
+import { transformJsonApiToSimplified } from '../lib/querying-writing/simplified-helpers.js';
+import { cascadeConfig } from './common.js';
+
+/**
+ * QUERY
+ * Retrieves a collection of resources (e.g., a list of articles) based on provided criteria.
+ * This function sends a GET request to /api/{resourceType}.
+ *
+ * @param {string} resourceType - The type of resource collection to fetch (e.g., "articles").
+ * @param {object} [queryParams={}] - Optional. An object to customize the query for the collection.
+ * @param {string[]} [queryParams.include=[]] - An optional array of relationship paths to sideload for each resource in the collection. These paths will be converted to a comma-separated string for the URL (e.g., `['author', 'comments.user']` becomes `author,comments.user`). Supports deep relationships (e.g., "publisher.country").
+ * @param {object} [queryParams.fields] - An object to request only specific fields (sparse fieldsets) for each resource in the collection and its included relationships. Keys are resource types, values are comma-separated field names.
+ * @param {object} [queryParams.filters] - An object to filter the collection. Keys are filter parameters (specific to your API's implementation, e.g., 'status', 'title'), values are the filter criteria.
+ * @param {string[]} [queryParams.sort=[]] - An optional array of fields to sort the collection by. Each string represents a field; prefix with '-' for descending order (e.g., `['title', '-published-date']` becomes `title,-published-date`).
+ * @param {object} [queryParams.page] - An object for pagination. Typically includes `number` (page number) and `size` (items per page). E.g., `{ number: 1, size: 10 }`.
+ * @returns {Promise<object>} A Promise that resolves to the JSON:API response document containing the resource collection.
+ */
+export default async function queryMethod({ 
+  params, 
+  context, 
+  vars, 
+  helpers, 
+  scope, 
+  scopes, 
+  runHooks, 
+  apiOptions, 
+  pluginOptions, 
+  scopeOptions, 
+  scopeName, 
+  log,
+  api 
+}) {
+  context.method = 'query';
+  
+  // Determine which simplified setting to use based on transport
+  const isTransport = params.isTransport === true;
+  
+  // Use vars which automatically cascade from scope to global
+  const defaultSimplified = isTransport ? vars.simplifiedTransport : vars.simplifiedApi;
+  
+  // Get simplified setting - from params only (per-call override) or use default
+  context.simplified = params.simplified !== undefined ? params.simplified : defaultSimplified;
+
+  // Assign common context properties
+  context.schemaInfo = scopes[scopeName].vars.schemaInfo; // This is the object variable created by compileSchemas
+  context.queryParams = params.queryParams || {};
+
+  // These only make sense as parameter per query
+  context.queryParams.fields = cascadeConfig('fields', [params.queryParams], {});
+  context.queryParams.include = cascadeConfig('include', [params.queryParams], []);
+  context.queryParams.sort = cascadeConfig('sort', [params.queryParams], []);
+  context.queryParams.page = cascadeConfig('page', [params.queryParams], {});
+
+  context.transaction = params.transaction;
+  context.db = context.transaction || api.knex.instance;
+  
+  context.scopeName = scopeName;
+
+  // These are just shortcuts used in this function and will be returned
+  const searchSchema = context.schemaInfo.searchSchema;
+  const schemaStructure = context.schemaInfo.schema.structure;
+  const schemaRelationships = context.schemaInfo.schemaRelationships;
+
+  // Sortable fields and sort (mab)
+  context.sortableFields = vars.sortableFields;
+  // Apply default sort if no sort specified
+  if (context.queryParams.sort.length === 0 && vars.defaultSort) {
+    context.queryParams.sort = Array.isArray(vars.defaultSort) ? vars.defaultSort : [vars.defaultSort];
+  }
+
+  // Validate query parameters to ensure they follow JSON:API specification and security rules.
+  // This checks that filters are valid field names, sort fields exist in sortableFields array
+  // (preventing SQL injection), pagination uses valid page[size]/page[number] format, and include
+  // paths reference real relationships. Example: sort: ['-createdAt', 'title'] is checked against
+  // sortableFields to ensure users can't sort by sensitive fields like 'password_hash'.
+  validateQueryPayload({ queryParams: context.queryParams }, context.sortableFields, vars.includeDepthLimit);
+
+  // Validate search/filter parameters against searchSchema
+  if (context.queryParams.filters && Object.keys(context.queryParams.filters).length > 0) {
+    // Only allow filtering if searchSchema is defined
+    if (!searchSchema) {
+      throw new RestApiValidationError(
+        `Filtering is not enabled for resource '${scopeName}'. To enable filtering, add 'search: true' to schema fields or define a searchSchema.`,
+        { 
+          fields: Object.keys(context.queryParams.filters).map(field => `filters.${field}`),
+          violations: [{
+            field: 'filters',
+            rule: 'filtering_not_enabled',
+            message: 'Resource does not have searchable fields defined'
+          }]
+        }
+      );
+    }
+  
+    // Validate the filter parameters searchSchema
+    const { validatedObject, errors } = await searchSchema.validate(context.queryParams.filters, { 
+      onlyObjectValues: true // Partial validation for filters
+    });
+
+    // If there are validation errors, throw an error
+    if (Object.keys(errors).length > 0) {
+      const violations = Object.entries(errors).map(([field, error]) => ({
+        field: `filters.${field}`,
+        rule: error.code || 'invalid_value',
+        message: error.message
+      }));
+      
+      throw new RestApiValidationError(
+        'Invalid filter parameters',
+        { 
+          fields: Object.keys(errors).map(field => `filters.${field}`),
+          violations 
+        }
+      );
+    }
+    
+    // Replace filter with validated/transformed values
+    context.queryParams.filters = validatedObject;
+  }
+
+  // Centralised checkPermissions function
+  await scope.checkPermissions({
+    method: 'query',
+    auth: context.auth,
+    transaction: context.transaction
+  });
+
+  await runHooks('beforeData');
+  await runHooks('beforeDataQuery');
+  context.record = await helpers.dataQuery({
+    scopeName,
+    context,
+    runHooks
+  });
+
+  // Normalize database values (e.g., convert 1/0 to true/false for booleans)
+  context.record = normalizeRecordAttributes(context.record, scopes);
+
+  // Make a backup
+  try {
+    context.originalRecord = structuredClone(context.record);
+  } catch (e) {
+    log.error('Failed to clone record:', {
+      error: e.message,
+      recordKeys: Object.keys(context.record || {}),
+      hasHttpRequest: !!context.raw?.req
+    });
+    throw e;
+  }
+
+  // This will enhance record, which is the WHOLE JSON:API record
+  await runHooks('enrichRecord');
+
+  // Get computed field information for main resource
+  const computedFields = scope.vars.schemaInfo?.computed || {};
+  const requestedFields = context.queryParams.fields?.[scopeName];
+  const requestedComputedFields = getRequestedComputedFields(scopeName, requestedFields, computedFields);
+
+  // Run enrichAttributes for every single set of attribute, calling it from the right scope
+  for (const entry of context.record.data) {
+    entry.attributes = await scope.enrichAttributes({ 
+      attributes: entry.attributes, 
+      parentContext: context,
+      requestedComputedFields: requestedComputedFields,
+      isMainResource: true,
+      computedDependencies: context.computedDependencies
+    });
+  }
+  for (const entry of (context.record.included || [])) {
+    const entryScope = scopes[entry.type];
+    const entryComputed = entryScope.vars.schemaInfo?.computed || {};
+    const entryRequestedFields = context.queryParams.fields?.[entry.type];
+    const entryRequestedComputed = getRequestedComputedFields(
+      entry.type, 
+      entryRequestedFields, 
+      entryComputed
+    );
+    
+    entry.attributes = await entryScope.enrichAttributes({ 
+      attributes: entry.attributes, 
+      parentContext: context,
+      requestedComputedFields: entryRequestedComputed,
+      isMainResource: false,
+      computedDependencies: entry.__$jsonrestapi_computed_deps$__
+    });
+  }
+
+  // The called hooks should NOT change context.record
+  await runHooks('finish');
+  await runHooks('finishQuery');
+  
+  // Transform output if in simplified mode
+  if (context.simplified) {
+    // Convert JSON:API response back to simplified format
+    // Example: {data: {type: 'posts', id: '1', attributes: {title: 'My Post'}, relationships: {author: {data: {type: 'users', id: '123'}}}}} 
+    // becomes: {id: '1', title: 'My Post', author_id: '123'} - flattens structure and restores foreign keys
+    return transformJsonApiToSimplified(
+      { record: context.record },
+      { context: { schemaStructure, schemaRelationships, scopes } }
+    );
+  }
+  
+  return context.record;
+}