Module: Ruact::ServerFunctions::Codegen::V2::QueryParams

Defined in:
lib/ruact/server_functions/codegen_v2_query_params.rb

Overview

Story 13.4 (FR99) — builds the TYPED query accessor params signature from the per-kwarg metadata QuerySource derives, and validates that metadata as a trust boundary. Extracted from Ruact::ServerFunctions::Codegen::V2 for the same reason Ruact::ServerFunctions::Codegen::V2 was extracted from Ruact::ServerFunctions::Codegen: keep each singleton class within its size budget. Constants (QUERY_SIGNATURE, QUERY_PARAMS_SIGNATURE, QUERY_PARAM_VALUE_TYPE, Ruact::ServerFunctions::Codegen::VALID_JS_IDENTIFIER, LINE_TERMINATORS) are reached from Ruact::ServerFunctions::Codegen via lexical scope.

MUST stay byte-identical to the JS-side querySignatureV2 / validateQueryParams in gem/vendor/javascript/vite-plugin-ruact/server-functions-codegen.mjs.

Class Method Summary collapse

Class Method Details

.signature(params:, params_rest:, accepts_params:) ⇒ String

Picks the query accessor's params signature.

When params is an Array (the Story 13.4 structured metadata), build a typed object literal — one property per declared keyword, required/optional exact, value type the FR88 wire union (AC1). Empty params + no **keyrest → the bare QUERY_SIGNATURE (byte-identical to a no-kwargs query). A **keyrest keeps the open Record<string, unknown> (intersected with any named keys) so a legitimate dynamic key is never narrowed away (fail open).

Falls back to the pre-13.4 accepts_params boolean when no params metadata is present (an older or hand-written snapshot) so no consumer breaks.

Parameters:

  • params (Array<Hash>, nil) —

    per-kwarg { "name", "required" }.

  • params_rest (Boolean, nil) —

    whether a **keyrest is declared.

  • accepts_params (Boolean, nil) —

    the back-compat fallback flag.

Returns:

  • (String) —

    the TS signature.



40
41
42
43
44
45
46
47
 
# File 'lib/ruact/server_functions/codegen_v2_query_params.rb', line 40

def signature(params:, params_rest:, accepts_params:)
  return fallback(accepts_params) unless params.is_a?(Array)

  rest = params_rest ? true : false
  return QUERY_SIGNATURE if params.empty? && !rest

  build(params, rest)
end

.validate!(js_id, params, params_rest = nil) ⇒ Object

Validates the structured params metadata. Reject a malformed or corrupted snapshot loudly rather than emit broken — or silently over-widened — TS. Absent params/params_rest is valid (the signature fallback handles it).

Parameters:

  • js_id (String)
  • params (Array<Hash>, nil)
  • params_rest (Object, nil) (defaults to: nil) —

    expected Boolean or nil; a non-Boolean truthy value would otherwise silently flip a query to the open & Record<string, unknown> shape (Story 13.4 review R1).

Raises:



60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/ruact/server_functions/codegen_v2_query_params.rb', line 60

def validate!(js_id, params, params_rest = nil)
  validate_rest!(js_id, params_rest)
  return if params.nil?

  unless params.is_a?(Array)
    raise Ruact::ConfigurationError,
          "ruact server-function codegen: v2 query entry #{js_id.inspect} has invalid " \
          "params #{params.inspect} (must be an Array of { name, required } objects)."
  end
  params.each { |param| validate_entry!(js_id, param) }
end